> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepSeek Harness

> Conectar o DeepSeek Harness à AIHubMix: instalação npm, provedor compatível com OpenAI, modelos auto ou específicos e teste de uma solicitação Agent.

O DeepSeek Harness (comando `dsh`) é o framework de agente de programação de código aberto da DeepSeek. Ele oferece espaços de trabalho, terminal, edição de arquivos, Skills, planejamento e Web UI. A interface compatível com OpenAI Chat Completions permite conectá-lo à AIHubMix.

<Info>
  Este guia foi testado em 14 de agosto de 2026 com o DeepSeek Harness `0.1.0-rc.6`. O Harness ainda está em versão prévia para desenvolvedores, portanto versões futuras podem alterar campos ou detalhes da interface.
</Info>

<h2 id="summary">
  Resumo
</h2>

A integração requer quatro valores:

| Configuração                 | Valor                     |
| ---------------------------- | ------------------------- |
| Provider ID                  | `aihubmix`                |
| Base URL                     | `https://aihubmix.com/v1` |
| API protocol                 | `openai-completions`      |
| API key environment variable | `AIHUBMIX_API_KEY`        |

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/01-models-aihubmix-configured.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=9a11531222d056d05d6ee6030eddb595" alt="AIHubMix configurada na página Models do DeepSeek Harness" width="1280" height="720" data-path="public/en/deepseek-harness/01-models-aihubmix-configured.png" />
</Frame>

<h2 id="requirements">
  O que é necessário?
</h2>

* Uma [chave de API da AIHubMix](https://console.aihubmix.com/token) ativa
* Node.js `22.19.0` ou posterior, incluindo Node.js 24+
* Acesso de rede ao registro npm e a `https://aihubmix.com`

```bash theme={null}
node --version
npm --version
```

<h2 id="install">
  Como instalar o DeepSeek Harness?
</h2>

Instale a versão publicada no npm sem clonar o repositório de código-fonte:

```bash theme={null}
npm install -g @deepseek-ai/dsh
dsh --version
```

Se aparecer `dsh: command not found`, execute `npm config get prefix` e confirme que o diretório `bin` correspondente está em `PATH`.

<h2 id="start-web-ui">
  Como iniciar a Web UI?
</h2>

Execute o comando no diretório que será usado como espaço de trabalho:

```bash theme={null}
dsh web --port 3080
```

Abra `http://127.0.0.1:3080` e selecione ou adicione um espaço de trabalho no primeiro uso.

<h2 id="configure-provider">
  Como configurar o provedor AIHubMix?
</h2>

Abra **Settings > Models > Add a custom provider**.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/03-add-custom-provider.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=e5f609447d3c979a65235ecc1b0382d0" alt="Formulário de provedor personalizado no DeepSeek Harness" width="1280" height="720" data-path="public/en/deepseek-harness/03-add-custom-provider.png" />
</Frame>

| Campo        | Valor recomendado            | Observações                                                       |
| ------------ | ---------------------------- | ----------------------------------------------------------------- |
| Provider ID  | `aihubmix`                   | Identificador em minúsculas; use `aihubmix-gateway` se necessário |
| Display name | `AIHubMix`                   | Nome exibido no seletor de modelos                                |
| Base URL     | `https://aihubmix.com/v1`    | Deve incluir `/v1`                                                |
| API protocol | `openai-completions`         | Protocolo compatível com OpenAI Chat Completions                  |
| API key      | Sua chave de API da AIHubMix | O Harness armazena como credencial e não exibe o valor novamente  |

O endpoint final é `https://aihubmix.com/v1/chat/completions`.

<Warning>
  Não informe o caminho completo `/chat/completions` no campo Base URL.
</Warning>

<h2 id="add-models">
  Adicionar auto ou outro modelo
</h2>

Depois de informar Base URL e a chave de API, selecione **Fetch available models**. O Harness solicita `GET https://aihubmix.com/v1/models` e mostra os IDs de modelo disponíveis.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/07-discover-models.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=7fdeeb8c4ba8400910bcabe1e7b50a78" alt="Modelos da AIHubMix disponíveis no DeepSeek Harness" width="1280" height="720" data-path="public/en/deepseek-harness/07-discover-models.png" />
</Frame>

Para o primeiro teste, você pode adicionar apenas `auto` com o nome `Auto`. Para usar um modelo específico, selecione-o na lista ou use **Add model** e informe o ID exato. O seletor gráfico mostra somente modelos registrados no catálogo do Provider atual.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/04-add-auto-model.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=0c1e93d53cf9840d5c5885dc192b0d80" alt="Adicionar manualmente o modelo auto da AIHubMix" width="1280" height="720" data-path="public/en/deepseek-harness/04-add-auto-model.png" />
</Frame>

Selecione **Create provider** para salvar.

<h2 id="auto-vs-specific-models">
  Comparação entre auto e um modelo específico
</h2>

| Opção                   | Quando usar                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `auto`                  | Primeiro teste de conexão ou seleção automática pela AIHubMix   |
| ID de modelo específico | É necessário fixar capacidade, versão ou resultado reproduzível |

As duas opções usam o mesmo Provider, Base URL e chave de API. Trocar de modelo não exige criar o provedor novamente.

<h2 id="environment-variables">
  Armazenar a chave de API em uma variável de ambiente
</h2>

Edite `$HOME/.dsh/settings.yaml`:

```yaml theme={null}
llm-pi-ai:
  providers:
    aihubmix:
      displayName: AIHubMix
      apiKeyEnv: AIHUBMIX_API_KEY
      api: openai-completions
      baseURL: https://aihubmix.com/v1
      models:
        - id: auto
          name: Auto
          contextWindow: 1000000
          maxTokens: 32768

agent-default-model:
  provider: aihubmix
  model: auto
```

```bash theme={null}
export AIHUBMIX_API_KEY='sk-***'
dsh web --port 3080
```

Quando a chave vem do ambiente de inicialização, a página de configurações mostra um aviso somente leitura sem revelar o valor.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/02-aihubmix-provider-details.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=a18af7f6409268331dcb4ddfa7d78568" alt="Detalhes do provedor AIHubMix no DeepSeek Harness" width="1280" height="720" data-path="public/en/deepseek-harness/02-aihubmix-provider-details.png" />
</Frame>

Reinicie o Harness depois de alterar a variável.

<h2 id="verify-chat">
  Selecionar um modelo e testar uma conversa
</h2>

Feche Settings e selecione **Auto** ou outro modelo adicionado no seletor localizado no canto inferior direito da caixa de entrada.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/05-select-auto-model.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=82577ac5295eebc0ef6e4945f75f5ffe" alt="Auto selecionado no DeepSeek Harness" width="1280" height="720" data-path="public/en/deepseek-harness/05-select-auto-model.png" />
</Frame>

```text theme={null}
Reply with exactly: AIHubMix connection successful
```

A resposta esperada confirma a conexão entre Harness, o endpoint compatível com OpenAI Chat Completions e AIHubMix.

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/06-live-chat-success.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=f5fe3902c1c2f57b84b34b739b258394" alt="Resposta bem-sucedida da AIHubMix no DeepSeek Harness" width="1280" height="720" data-path="public/en/deepseek-harness/06-live-chat-success.png" />
</Frame>

<h2 id="headless-test">
  Executar um teste headless
</h2>

```bash theme={null}
export AIHUBMIX_API_KEY='sk-***'
dsh --profile headless \
  'Reply with exactly DSH_AIHUBMIX_OK and do not use tools.'
```

Uma execução bem-sucedida mostra `DSH_AIHUBMIX_OK`.

<h2 id="troubleshooting">
  Perguntas frequentes
</h2>

<h3 id="missing-credential">
  Por que aparece MISSING\_CREDENTIAL?
</h3>

O Harness não recebeu `AIHUBMIX_API_KEY` do ambiente de inicialização. Defina a variável e inicie o Harness no mesmo terminal.

<h3 id="models-401">
  Por que a busca de modelos retorna 401?
</h3>

Confirme que a chave de API é válida e não contém espaços ou quebras de linha extras. A solicitação usa autenticação Bearer.

<h3 id="only-auto">
  Por que Auto é o único modelo no seletor?
</h3>

O seletor mostra somente modelos registrados no catálogo atual. Abra **Settings > Models > AIHubMix > Edit** e use **Fetch available models**, ou adicione manualmente o ID exato.

<h3 id="unknown-model">
  Por que o Harness mostra UNKNOWN\_MODEL?
</h3>

O catálogo atual não contém esse ID. IDs diferenciam maiúsculas e minúsculas, use o valor exato retornado pela busca.

<h3 id="connection-timeout">
  Por que a conexão expira?
</h3>

Verifique DNS, a rede da organização e o proxy local. Se somente o navegador usa o proxy do sistema, defina `HTTP_PROXY`, `HTTPS_PROXY` e `NODE_USE_ENV_PROXY=1` no terminal que inicia `dsh`.

<h2 id="security">
  Recomendações de segurança
</h2>

* Não inclua chaves de API no Git, em capturas de tela ou scripts compartilhados
* Use o armazenamento de credenciais do Harness ou `AIHUBMIX_API_KEY`
* Não exiba a chave de API completa durante o diagnóstico
* Use o gerenciamento de segredos da plataforma CI para injetar variáveis

***

Última atualização: 2026-08-14