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

# DeepSeek Harness Integration Coding Plan

> DeepSeek AI API guide - Ace Data Cloud

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) é um agente de programação que roda localmente. Ele lê o espaço de trabalho, chama ferramentas e executa comandos, e então chama o modelo através da interface de Chat Completions compatível com OpenAI.

> Este documento é aplicável a `deepseek-harness-sdk==0.1.0rc6` e `deepseek-harness-runtime-bin==0.1.0rc6`. Após atualizar o cliente, por favor, reexecute os testes de arquivo somente leitura abaixo.

## Escopo de Suporte

| Item | Configuração |
| - | - |
| URL Base da API | `https://api.acedata.cloud/v1` |
| Modelo | `deepseek-v4-pro` |
| Protocolo | Chat Completions compatível com OpenAI (streaming) |
| Capacidades | Texto, processo de raciocínio, chamadas de ferramentas de função, loop de ferramentas Bash local, estatísticas de uso |

O diretório do modelo pode mudar. Antes de executar, consulte o diretório em tempo real usando a chave exclusiva do Coding Plan:

```bash theme={null}
curl https://api.acedata.cloud/v1/models \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY"
```

Confirme que a resposta contém `deepseek-v4-pro`. Não considere `deepseek-v4-flash` como um substituto equivalente ao modo de ferramenta deste documento; na validação de versão fixa, seu histórico de raciocínio em múltiplas rodadas e a reprodução de ferramentas não passaram.

## 1. Preparar Chave Exclusiva

Abra o [Aplicativo Coding Plan](https://platform.acedata.cloud/console/applications), acesse o Aplicativo de Codificação adquirido, crie ou copie a chave API exclusiva desse aplicativo. O Coding Plan não utiliza saldo genérico, as chaves de outros aplicativos não podem representar permissões de pacote.

Coloque a chave apenas no shell atual:

```bash theme={null}
export ACEDATACLOUD_API_KEY="COLE_SUA_CHAVE_DE_CODIFICAÇÃO_AQUI"
export DEEPSEEK_BASE_URL="https://api.acedata.cloud/v1"
export DEEPSEEK_API_KEY="$ACEDATACLOUD_API_KEY"
```

Não escreva a chave real em scripts, repositórios de configuração, capturas de tela de terminal ou registros de sessão.

## 2. Criar Espaço de Trabalho Isolado

O runtime empacotado do Harness inclui ferramentas Bash locais. Na primeira validação, não aponte para projetos reais ou diretórios principais; crie um diretório descartável sem segredos:

```bash theme={null}
mkdir -p /tmp/deepseek-harness-demo/workspace
mkdir -p /tmp/deepseek-harness-demo/sessions
printf 'compatibility fixture\n' > /tmp/deepseek-harness-demo/workspace/fixture.txt
python3 -m venv /tmp/deepseek-harness-demo/venv
/tmp/deepseek-harness-demo/venv/bin/pip install \
  "deepseek-harness-sdk==0.1.0rc6"
```

Se a rede da empresa usar um espelho PyPI privado, confirme primeiro que a mesma versão de `deepseek-harness-runtime-bin` também está presente no espelho. Não use `danger-full-access` para ampliar o escopo de acesso a arquivos; o exemplo deste documento apenas passa o diretório descartável para `cwd`.

## 3. Executar o SDK Python Oficial

Salve o conteúdo abaixo como `/tmp/deepseek-harness-demo/run.py`:

```python theme={null}
import os

from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-pro",
    max_tokens=160,
    cwd="/tmp/deepseek-harness-demo/workspace",
    session_root="/tmp/deepseek-harness-demo/sessions",
    base_url=os.environ["DEEPSEEK_BASE_URL"],
    api_key=os.environ["DEEPSEEK_API_KEY"],
    request_timeout_seconds=180,
) as harness:
    result = harness.run(
        "Read fixture.txt once, then reply with exactly: sdk-harness-ok",
        session_id="acedatacloud-compat",
    )

print(result.final_response)
print(result.finish_reason)
```

Execute:

```bash theme={null}
/tmp/deepseek-harness-demo/venv/bin/python \
  /tmp/deepseek-harness-demo/run.py
```

Resultado esperado:

```text theme={null}
sdk-harness-ok
completed
```

Esta etapa valida simultaneamente a autenticação Bearer, `/v1/chat/completions`, SSE, conteúdo de raciocínio, chamadas de ferramentas e retorno de resultados de ferramentas. Após a conclusão, você pode excluir `/tmp/deepseek-harness-demo`; se o diretório de sessão contiver contexto do projeto, ele também deve ser armazenado com o mesmo nível de sensibilidade que o repositório de código.

## Perguntas Frequentes

* **401**: Verifique se `ACEDATACLOUD_API_KEY` está exportado para o mesmo shell que executa o Python.
* **403 ou aviso de cota**: Confirme se a chave pertence ao Aplicativo de Codificação atual, se o pacote ainda está dentro do período de validade e se há saldo restante.
* **Modelo indisponível**: Consulte novamente `/v1/models`, não adivinhe o nome do modelo com base em capturas de tela antigas.
* **Erro em `reasoning_content` / reprodução de ferramentas**: Confirme se o SDK/runtime estão na versão fixa deste documento e se está usando `deepseek-v4-pro`.
* **Número de execuções de ferramentas anômalo**: Pare a execução de tarefas que podem ter efeitos colaterais, primeiro valide a versão atual do serviço usando o fixture somente leitura deste documento.
* **Falha na instalação**: Confirme se Python 3.10+, a arquitetura do sistema operacional é suportada pela roda atual e verifique se as versões do SDK/runtime são consistentes.

## Limites de Capacidade

Este documento valida apenas o SDK Python local até as Chat Completions em texto e loop de ferramentas. Imagens, API de Arquivos, `/v1/responses`, `/v1/messages`, espaço de trabalho remoto e sandbox hospedado não estão dentro do escopo prometido deste tutorial; as permissões do espaço de trabalho e os riscos de comandos locais são de responsabilidade da máquina e configuração que executa o Harness.

## Referência Oficial

* [Repositório DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
* [SDK Python DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/sdk/README.md)

Retorne ao [Centro de Configuração do Coding Plan](https://platform.acedata.cloud/documents/coding-plan-integration).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.