Dify na Rússia: API compatível com OpenAI e seu primeiro workflow

O Dify pode conectar uma API externa por meio do provedor de modelos oficial OpenAI-API-compatible. Você precisa da sua própria API Key, de uma Base URL compatível e de um Model ID atual. Para verificar a configuração, monte um workflow com entrada de texto, um nó LLM e saída de texto; execute-o uma vez e compare o resultado com o registro do provedor.

Precisa da sua própria API Key para este workflow? Crie uma conta BetterToken

Para testar o Dify com um único workflow e sem ações externas, use uma chave de teste separada da BetterToken e abra o guia atual do Dify. Ele cobre o acesso à API de modelos. A instalação do Dify, o Marketplace, plugins de terceiros, agents e tools continuam sendo camadas separadas.

O que preparar

• uma instância funcional do Dify Cloud ou uma instalação auto-hospedada do Dify;
• acesso a Integrations/Marketplace e Model Providers;
• sua própria API Key da BetterToken;
• um Model ID atual da model plaza da BetterToken;
• um novo workflow de teste, sem tools nem ações externas.

Na Rússia, é possível conectar-se ao endpoint da API BetterToken sem VPN. Isso não garante a disponibilidade do Dify Cloud, Marketplace, GitHub, de um registry Docker ou de plugins de terceiros.

1. Instale o provedor oficial

No Dify, abra Integrations ou Marketplace e depois Model Providers. Encontre o provedor oficial OpenAI-API-compatible e instale-o se ainda não estiver disponível.

Confira o autor e a página do item no Marketplace oficial do Dify. Não use um plugin aleatório com nome semelhante: os campos e o tratamento de credentials podem ser diferentes.

2. Adicione um modelo BetterToken

Abra as configurações do provedor e adicione um novo modelo LLM. Preencha:

1. Model Type: LLM.
2. Model Name / ID: o Model ID atual exato.
3. API Key: sua própria API Key da BetterToken.
4. API Base URL: https://www.bettertoken.ai/v1.
5. Completion mode: Chat, se o provedor e o modelo escolhidos exigirem isso.

Não acrescente /chat/completions à Base URL: o provedor monta o caminho completo. Não copie credentials reais para uma exportação do aplicativo, captura de tela ou issue.

Se a interface solicitar tamanho de contexto, max tokens, parâmetros de vision ou streaming, use apenas valores da documentação atual do modelo. O primeiro teste não precisa de recursos extras.

3. Salve e valide o credential

O Dify valida o credential ao salvá-lo. Isso comprova apenas que o provedor conseguiu concluir seu procedimento de autenticação; o workflow completo ainda não foi validado.

Depois de um erro, mantenha somente dados seguros para diagnóstico:

• nome e versão do provedor;
• Model ID;
• Base URL sem a chave;
• tipo de erro curto e status HTTP;
• horário da tentativa.

Não guarde a API Key nem uma resposta sensível completa.

4. Crie um workflow mínimo

Crie um novo aplicativo do tipo Workflow. Adicione somente três elementos:

1. Start com uma variável de texto chamada question.
2. LLM usando o modelo BetterToken adicionado.
3. End com o texto da resposta do LLM.

Use este template simples de prompt para o LLM:

Responda em uma linha. Entrada: {{question}}

Conecte Start → LLM → End. Não adicione ferramentas HTTP, banco de dados, recuperação de conhecimento, loop de agent ou publicação. Eles tornam a primeira falha mais difícil de isolar.

5. Execute um teste

Use esta entrada:

Retorne DIFY_OK e o número 4 como a soma de 2 + 2.

A configuração estará confirmada quando:

• o Dify mostrar a saída de texto esperada;
• o nó LLM terminar sem erro de credential, modelo ou endpoint;
• o Dashboard da BetterToken mostrar um registro com o modelo e o status esperados;
• o Dashboard mostrar tokens de entrada, saída, cache quando aplicável e a cobrança correspondente.

Comparar a execução do Dify com o Dashboard evita concluir que o workflow funcionou quando, sem perceber, ele usou outro provedor ou modelo.

Como diferenciar erros

O provedor ou plugin não instala

Esse é um problema da camada Dify Marketplace/plugin-daemon. Em ambiente auto-hospedado, verifique a versão do Dify, o acesso de rede do plugin daemon, HTTPS e a cadeia de certificados. Trocar a API Key da BetterToken não resolverá esse erro.

ToolProviderCredentialValidationError ou 401

Digite a chave novamente, verifique espaços e confirme o provedor selecionado. Certifique-se de que o credential pertence ao modelo, e não a um plugin de ferramenta sem relação.

404

Verifique a Base URL:

https://www.bettertoken.ai/v1

Remova um /chat/completions adicionado manualmente se o campo esperar uma API Base URL.

model not found

Copie o ID atual da model plaza. Confirme que esse ID está disponível para a nova chave e para o provedor compatível com OpenAI selecionado.

O credential é salvo, mas o workflow falha

Teste o nó LLM isoladamente. Remova tools, streaming e saída estruturada; em seguida, repita a execução curta de texto de entrada/texto de saída. Se ela passar, restaure os nós extras um a um.

Escopo desta configuração

O primeiro workflow confirma uma requisição de modelo pelo provedor oficial OpenAI-API-compatible. Ele não prova compatibilidade com todos os agents, plugins da comunidade, tools ou serviços externos do Dify. Crie um teste separado para cada ação com efeito colateral e exija confirmação explícita do usuário.

Os campos e limites atuais estão na documentação BetterToken para Dify. Confira Model IDs e preços dinâmicos no dia da configuração.