Como Rodar Qualquer Modelo no DeepSeek Harness

DeepSeek Harness (dsh) vem com os modelos próprios do DeepSeek integrados, mas você não está preso a eles. O harness trata os provedores de modelo como configuração: aponte um bloco de provedor para qualquer endpoint compatível com OpenAI, forneça uma referência de credencial, e suas sessões de agente rodarão em qualquer modelo que esteja por trás daquela URL. Uma instância local do Ollama, um gateway corporativo, Qwen através do modo compatível do DashScope, ou os grandes provedores de catálogo como Anthropic e OpenAI, todos se conectam ao mesmo bloco.

Este guia detalha esse bloco chave por chave, e então constrói três receitas funcionais: um modelo local, um endpoint hospedado compatível com OpenAI e os provedores de catálogo integrados. Tudo o que está citado aqui vem do guia de provedores oficial no branch master, obtido em 20 de agosto de 2026. Um aviso inicial: dsh é uma prévia para desenvolvedores, e o README adverte em letras maiúsculas que haverá mudanças que quebrarão a compatibilidade. Verifique a documentação em relação à sua versão instalada antes de copiar qualquer coisa para produção.

Se você é novo no harness, comece com o que é DeepSeek Harness e como funciona, e depois volte aqui para a configuração dos provedores.

Por que trocar modelos em um agent harness

Um agent harness é um loop: o modelo planeja, chama ferramentas, lê resultados e repete. O harness é responsável pelo loop; o modelo é um ingrediente. Três razões pelas quais você mudaria o ingrediente:

Custo. Sessões de agente consomem tokens rapidamente porque cada resultado de ferramenta é alimentado de volta ao contexto. Direcionar sessões rotineiras para um modelo mais barato, ou para o DeepSeek V4-Flash em vez do V4-Pro, muda sua fatura sem alterar seu fluxo de trabalho. Você pode manter um modelo de ponta caro configurado para as sessões que precisam dele.

Localidade de dados. Algumas bases de código não podem sair da empresa. Um bloco de provedor apontado para um modelo rodando em seu próprio hardware significa que prompts, conteúdos de arquivos e saídas de ferramentas nunca atravessam a rede. O mesmo harness, a mesma UI, zero egresso.

Desenvolvimento local. Ao construir plugins ou testar o comportamento de agentes, você não quer que cada iteração custe créditos de API ou dependa de sua rede. Um pequeno modelo local responde rápido o suficiente para testar o loop, e você troca pelo modelo real quando o comportamento importa.

O design segue a arquitetura do dsh: tudo no harness é um plugin, e o adaptador de modelo é uma das peças substituíveis. As rotas de provedor são de propriedade do plugin dsh-llm-pi-ai, que é documentado no catálogo de configuração de plugins do repositório como contendo “rotas de provedor que esta instância possui”. Essa é a maquinaria. A interface voltada para o usuário é um bloco YAML.

O bloco de provedor, chave por chave

Provedores personalizados residem em $DSH_HOME/settings.yaml, e você também pode criá-los a partir da UI web em Configurações → Modelos. Aqui está o exemplo direto da documentação oficial:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

O que cada chave faz:

• my-gateway é o ID do provedor. É um identificador permanente, então escolha um nome com o qual você possa viver; o nome de exibição mostrado na UI é configurado separadamente.
• apiKeyEnv nomeia a variável de ambiente que contém sua chave de API. O arquivo de configurações nunca contém o segredo em si, apenas esta referência. Mais sobre onde a chave real reside abaixo.
• api declara o protocolo de comunicação. openai-completions é o valor documentado para endpoints compatíveis com OpenAI, o que faz com que a promessa de "qualquer modelo" funcione: a maioria dos gateways, runtimes locais e provedores hospedados falam este protocolo.
• baseURL é a raiz do endpoint para onde o harness envia as requisições.
• models lista os IDs de modelo disponíveis através deste provedor. Cada entrada precisa de pelo menos um id, que deve corresponder ao que o endpoint espera no corpo da requisição.
• input declara as modalidades por modelo. Modelos personalizados são padrão somente texto, então um modelo de visão deve declarar explicitamente input: [text, image] ou os anexos de imagem não o alcançarão. Há também um defaultInput em nível de rota que define um fallback para cada modelo no provedor; um input em nível de modelo o sobrescreve.
• compat contém chaves de compatibilidade para endpoints que se desviam do comportamento padrão do OpenAI. A documentação destaca duas: `supportsDeveloperRole: false` para backends que rejeitam a função `developer`, e `maxTokensField: max_tokens` para backends que querem o nome de campo de limite de saída mais antigo. `compat` pode ser definido em nível de rota ou por modelo.

Uma conveniência que vale a pena saber: ao adicionar um provedor personalizado através da UI web, uma opção “Buscar modelos disponíveis” consulta a rota GET /models compatível com OpenAI do endpoint e preenche a lista de modelos para você. Se o seu endpoint implementar essa rota, você pula a digitação manual.

Onde a chave de API real reside

Segredos são armazenados somente para escrita em $DSH_HOME/.credentials.yaml. Depois de salvar uma chave através da UI, o dsh retorna apenas um descritor redigido; o valor literal nunca mais é exibido. settings.yaml contém referências (nomes `apiKeyEnv`, descritores de credenciais), nunca as chaves em si. Essa separação significa que você pode commitar ou compartilhar um arquivo de configurações sem vazar nada, e rotacionar uma chave sem tocar na configuração do provedor.

Receita 1: executar um modelo local através do Ollama

Ollama expõe uma API compatível com OpenAI em http://localhost:11434/v1, que o Ollama documenta em seu próprio guia de compatibilidade OpenAI. Como o dsh se comunica via openai-completions com qualquer URL base, a conexão é direta.

[VERIFICAR: a documentação do dsh não mostra um exemplo específico do Ollama; esta receita aplica o esquema de provedor personalizado documentado ao endpoint compatível com OpenAI documentado do Ollama. Teste em sua instalação antes de publicar internamente.]

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3

Notas sobre este:

• Ollama não requer uma chave de API localmente, mas o esquema espera uma referência de credencial, então defina um valor fictício: `export OLLAMA_API_KEY=ollama`. Ollama ignora o que você enviar.
• O `id` do modelo deve corresponder à tag que o Ollama serve. Execute `ollama list` e copie os nomes exatamente, incluindo a tag.
• Puxe o modelo primeiro (`ollama pull gpt-oss:20b`) e confirme se o servidor responde antes de conectá-lo ao dsh. Cobrimos a configuração local completa em como executar GPT-OSS usando Ollama, e o mesmo padrão funciona para outros modelos de peso aberto como Kimi K3 se seu hardware for adequado.

Uma rápida verificação de sanidade evita uma sessão de agente confusa: acesse http://localhost:11434/v1/models no Apidog antes de tocar na configuração do dsh. Se essa requisição retornar sua lista de modelos, a URL base está correta, o servidor está ativo, e “Buscar modelos disponíveis” na UI do dsh também funcionará. Se não funcionar, nenhuma quantidade de configuração do harness irá consertar.

Gerenciamento de expectativas: agent harnesses dependem muito da chamada de ferramentas e de contexto longo. Pequenos modelos locais lidam com o loop para testes, mas eles planejarão pior e perderão chamadas de ferramentas com mais frequência do que os modelos de ponta para os quais o harness foi construído. Isso é bom para o desenvolvimento de plugins; é frustrante para o trabalho real.

Receita 2: um endpoint hospedado compatível com OpenAI (Qwen via DashScope)

Para um exemplo hospedado, escolha um fornecedor que documente sua compatibilidade com OpenAI em vez de um que você presume ter. O Alibaba Cloud Model Studio (DashScope) o faz: sua página de compatibilidade com OpenAI documenta um endpoint /compatible-mode/v1 para modelos Qwen, com domínios regionais e específicos de workspace (para Cingapura: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1) e autenticação via variável de ambiente DASHSCOPE_API_KEY.

Mapeado para o esquema dsh:

llm-pi-ai:
  providers:
    qwen-dashscope:
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3-max

Substitua {WorkspaceId} pelo seu domínio de workspace real do console do Model Studio, e verifique a lista de modelos do fornecedor para os IDs atuais; mantemos um resumo da camada principal em nosso guia da API Qwen 3.8. O mesmo padrão se estende a qualquer fornecedor com compatibilidade OpenAI documentada: API Kimi da Moonshot, OpenRouter, um deployment vLLM ou o gateway interno de sua empresa. As únicas partes que mudam são baseURL, o nome da variável de ambiente e os IDs dos modelos. Se você configurou modelos de código aberto no Codex, isso parecerá familiar; o bloco YAML do dsh desempenha o mesmo papel que a configuração model_providers do Codex.

Duas especificidades de endpoint hospedado:

• Se o endpoint do fornecedor rejeitar requisições com erros estranhos sobre roles ou campos de token, é para isso que existem as chaves `compat`. Tente `supportsDeveloperRole: false` primeiro; implementações mais antigas compatíveis com OpenAI são anteriores à role `developer`.
• Modelos de visão devem declarar `input: [text, image]` explicitamente, mesmo que o modelo hospedado suporte imagens. O dsh assume apenas texto para modelos personalizados, a menos que seja instruído de outra forma.

Receita 3: os provedores de catálogo integrados

Você não precisa de um bloco personalizado para as nuvens principais. O dsh vem com provedores de catálogo para DeepSeek, Anthropic e OpenAI, onde a configuração é principalmente “colar uma chave de API”. Entradas de catálogo especiais possuem seus próprios fluxos de autenticação nativos: Bedrock usa credenciais AWS, Vertex quer um projeto ADC, Azure precisa de sua api-version, e Codex autentica via OAuth.

Provedores de catálogo são o caminho de baixa fricção quando você apenas quer Claude ou GPT por trás do harness, e é assim que a maioria das pessoas executará o DeepSeek V4-Pro, cujo lançamento da API em agosto de 2026 chegou junto com o próprio harness (detalhes em api-docs.deepseek.com). Provedores personalizados são para tudo o que o catálogo não cobre: runtimes locais, gateways, fornecedores regionais e agregadores compatíveis com OpenAI.

Selecionando o modelo e o que as sessões lembram

Adicionar um provedor torna seus modelos disponíveis; selecionar um modelo em Configurações → Modelos o torna o padrão para novas sessões. Dois comportamentos da documentação que valem a pena internalizar:

1. Sessões existentes mantêm o modelo com o qual foram iniciadas. As sessões registram seu modelo original, então mudar o padrão no meio do projeto não reescreve silenciosamente o histórico nem altera o que uma sessão em andamento usa.
2. Se você deletar o provedor que possui o padrão atual, o compositor bloqueará a entrada até que você escolha um novo modelo. O harness falha ruidosamente em vez de adivinhar.

Essa fixação de sessão é importante para a reprodutibilidade: ao comparar o dsh com outros harnesses (fizemos exatamente isso em DeepSeek Harness vs Claude Code), você pode confiar que a transcrição de uma sessão reflete um modelo, e não uma troca no meio da execução.

Solucionando falhas comuns

`baseURL` incorreta ou inalcançável. A falha mais comum é a menos exótica. Confirme que a URL termina onde o protocolo espera (geralmente `/v1` para endpoints compatíveis com OpenAI, `/compatible-mode/v1` para DashScope) e que um simples `GET {baseURL}/models` é bem-sucedido fora do harness. Este é o ponto de verificação onde o Download Apidog se paga em cinco minutos: envie a requisição com o mesmo cabeçalho (`Authorization: Bearer $KEY`) que o harness enviará, e leia o código de status e o corpo reais em vez de um erro encapsulado do harness. Se você estiver desenvolvendo offline ou o fornecedor for instável, simule as respostas de `/models` e `/chat/completions` do provedor no Apidog e aponte o `baseURL` para a simulação enquanto você constrói.

Variável de ambiente ausente ou vazia. `apiKeyEnv` nomeia uma variável; não a cria. Se a variável não estiver definida no ambiente em que o dsh realmente é executado, as requisições sairão não autenticadas e retornarão 401. Lembre-se de que um processo iniciado a partir de uma GUI ou de um gerenciador de serviços pode não herdar seu perfil de shell. `echo $GATEWAY_API_KEY` no mesmo contexto que inicia `dsh web`, não apenas em um terminal aleatório.

Incompatibilidade de modalidade de entrada. Você anexa uma imagem, e o modelo nunca a vê, ou a requisição gera erros. Modelos personalizados são somente texto por padrão. Adicione `input: [text, image]` na entrada do modelo, ou defina `defaultInput` no nível da rota se todos os modelos do provedor lidam com imagens.

Peculiaridades do protocolo. Erros mencionando uma role não suportada ou um parâmetro de token rejeitado apontam para chaves de compatibilidade: `supportsDeveloperRole: false` e `maxTokensField: max_tokens` são as duas documentadas.

Tudo funcionou ontem. Prévia para desenvolvedores. Fixe a versão que você implanta, leia as notas de lançamento antes de atualizar e espere que o esquema de configurações mude. O repositório deepseek-harness é a fonte da verdade, não qualquer post de blog, incluindo este.

Mais uma nota de integração: provedores de modelo são apenas metade da história de personalização. A outra metade são as ferramentas que o agente pode chamar, e você pode integrar seus fluxos de trabalho de API diretamente; cobrimos isso em usando Apidog CLI dentro do DeepSeek Harness.

FAQ

O DeepSeek Harness suporta Ollama oficialmente?

A documentação oficial de provedores não menciona Ollama pelo nome. O que ela suporta é qualquer endpoint que se comunique via protocolo `openai-completions`, e o Ollama documenta uma API compatível com OpenAI em `http://localhost:11434/v1`. A receita acima combina as duas metades documentadas; teste em sua instalação, já que o dsh é uma prévia para desenvolvedores e os esquemas podem mudar entre lançamentos.

Onde o dsh armazena minhas chaves de API?

Em $DSH_HOME/.credentials.yaml, somente para escrita. A UI mostra um descritor redigido após salvar, e settings.yaml contém apenas referências como nomes `apiKeyEnv`. Você nunca terá uma chave em texto simples dentro da configuração do seu provedor.

Posso executar modelos diferentes para sessões diferentes?

Sim. Selecionar um modelo define o padrão apenas para novas sessões; cada sessão existente mantém o modelo com o qual foi iniciada. Assim, você pode executar um modelo barato como o DeepSeek V4-Flash para sessões rotineiras, mudar o padrão para um modelo mais robusto para um problema difícil, e suas sessões anteriores permanecem intocadas.

Meu endpoint personalizado retorna erros que a mesma requisição não produz no curl. E agora?

Compare os payloads exatos. O harness pode enviar uma role `developer` ou um campo de limite de token mais recente que seu backend não aceita; as correções documentadas são `supportsDeveloperRole: false` e `maxTokensField: max_tokens` sob `compat`. Reproduzir a requisição formatada pelo harness em um cliente de API mostra qual campo o backend está rejeitando.