Pi

O Pi pode ligar-se à HiAPI através do models.json. Os passos abaixo usam deepseek-v4.1-flash como exemplo; este tutorial foi verificado no Mac com o Pi 1.3.0. No Windows, instale primeiro o Git Bash (passo 3).

1. Instalar o Node.js

Instale a LTS 22.19 ou posterior como descrito em Configuração do Node.js e ignore se já a tiver. Depois execute os dois comandos abaixo num terminal; ver números de versão é suficiente:

node --version
npm --version

No Windows PowerShell, escreva os comandos npm / npx mais adiante neste guia como npm.cmd / npx.cmd.

2. Instalar o Pi

Execute cada linha num terminal:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0
pi --version

Ver 1.3.0 é suficiente. No Windows PowerShell, use npm.cmd install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0 e pi.cmd --version.

3. Instalar primeiro o Git Bash no Windows (ignore no Mac)

1. Abra a página de transferência do Git for Windows, transfira o instalador para a sua arquitetura e execute-o. Mantenha o diretório de instalação como C:\Program Files\Git, escolha a opção de PATH recomendada Git from the command line and also from 3rd-party software e clique em Install → Finish. Ignore isto se já tiver o Git Bash.
2. Feche a janela antiga do PowerShell, volte a abri-la e confirme o caminho do Bash:

& 'C:\Program Files\Git\bin\bash.exe' --version

Ver uma versão GNU bash é suficiente. Se instalou noutro local, encontre o bin\bash.exe real no Explorador de Ficheiros e substitua o caminho no comando.

3. O Pi normalmente encontra o Git Bash automaticamente. Só se continuar a indicar que o Bash não foi encontrado depois de iniciar é que deve abrir %USERPROFILE%\.pi\agent\settings.json no Notepad (faça primeiro uma cópia de segurança de um ficheiro existente), adicionar ou atualizar o campo shellPath e manter os outros campos:

{
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}

Use o seu caminho de instalação real e escreva as barras invertidas duas vezes. Em Save as, escolha «All files», UTF-8, nome de ficheiro settings.json e volte a abrir o Pi depois de guardar.

4. Obter uma HiAPI API key

Prepare uma chave como descrito em Obter uma chave de API, clique no ícone de copiar junto à chave e copie a HiAPI API key completa; vai precisar dela no passo 7.

5. Abrir o ficheiro de configuração de modelos

Num Mac, execute cada linha num terminal (um models.json existente é primeiro copiado automaticamente para uma cópia de segurança):

mkdir -p "$HOME/.pi/agent"
if [ -f "$HOME/.pi/agent/models.json" ]; then cp "$HOME/.pi/agent/models.json" "$HOME/.pi/agent/models.json.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.pi/agent/models.json"

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.pi\agent"
if (Test-Path "$env:USERPROFILE\.pi\agent\models.json") { Copy-Item "$env:USERPROFILE\.pi\agent\models.json" "$env:USERPROFILE\.pi\agent\models.json.bak-$(Get-Date -Format yyyyMMdd-HHmmss)" }
notepad "$env:USERPROFILE\.pi\agent\models.json"

Se tiver definido PI_CODING_AGENT_DIR, edite models.json nesse diretório; se não, use o diretório predefinido acima.

6. Adicionar a configuração do DeepSeek e guardar

1. Escreva o conteúdo abaixo em models.json (não o execute linha a linha no terminal). Para um ficheiro novo, cole tudo; se o ficheiro existir, apenas funda hiapi-deepseek nos providers existentes, mantenha os outros fornecedores e deixe exatamente um providers de nível superior.

{
  "providers": {
    "hiapi-deepseek": {
      "baseUrl": "https://api.hiapi.ai/v1",
      "api": "openai-completions",
      "apiKey": "${HIAPI_API_KEY}",
      "models": [
        {
          "id": "deepseek-v4.1-flash",
          "name": "DeepSeek V4.1 Flash (HiAPI)",
          "api": "openai-completions",
          "reasoning": true,
          "input": [
            "text"
          ],
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "thinkingLevelMap": {
            "minimal": null,
            "low": "low",
            "medium": null,
            "high": "high",
            "xhigh": null,
            "max": "max"
          },
          "compat": {
            "thinkingFormat": "deepseek",
            "maxTokensField": "max_tokens",
            "supportsReasoningEffort": true
          }
        }
      ]
    }
  }
}

2. Em apiKey, ${HIAPI_API_KEY} é a forma como o Pi lê uma variável de ambiente; deixe como está e defina a chave no passo seguinte. Use aspas duplas e vírgulas no JSON, sem vírgula à direita do último item e sem comentários.

① Adicione o objeto hiapi-deepseek completo em providers; ② mantenha o marcador da variável de ambiente em apiKey. Os outros fornecedores já presentes na captura de ecrã podem ficar.

3. Guardar: no nano do Mac prima Ctrl+O → Enter → Ctrl+X; no Notepad do Windows escolha Save as, «All files», UTF-8, e dê ao ficheiro exatamente o nome models.json, não .json.txt.

7. Definir a API key e iniciar o Pi

1. Num Mac, execute isto no mesmo terminal onde vai iniciar o Pi (substitua YOUR_HIAPI_API_KEY pela sua HiAPI API key e mantenha as aspas):

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"

2. Vá para a pasta do seu projeto e inicie o Pi, ou crie primeiro um diretório vazio:

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
pi

Windows PowerShell:

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
pi.cmd

3. A variável de ambiente só se aplica ao terminal atual; defina-a novamente depois de fechar o terminal. Com a HiAPI não precisa de executar /login no Pi.

8. Escolher um modelo e verificar

1. Na caixa de entrada do Pi, escreva /model e prima Enter, procure hiapi, use as teclas de seta para selecionar DeepSeek V4.1 Flash (HiAPI) (fornecedor hiapi-deepseek) e prima Enter.

① Mova-se para a linha DeepSeek com as teclas de seta; ② prima Enter para a selecionar.

2. Escreva /thinking e prima Enter, escolha um de off / low / high / max e prima Enter; para uma primeira tentativa, escolha low.

① Escolha um de off, low, high, max; ② prima Enter para o aplicar à sessão atual.

3. Enter só se aplica à sessão atual; para tornar este nível o predefinido para sessões futuras, prima Ctrl+S como o menu sugere.

4. Envie «Olá, apresente-se numa frase.». Uma resposta normal significa que a ligação funciona. Se Registos de pedidos na consola da HiAPI mostrar este pedido, está a passar pela HiAPI.

Resolução de problemas

Aqui só estão listados problemas específicos do Pi. Para erros comuns como 401, 404 e 429, consulte Erros comuns.