Provedores personalizados permitem que o PandaNpc use uma conta de API, gateway privado ou endpoint de modelo local que você controla. Isso é comumente chamado de BYOK: traga sua própria chave. É útil quando você precisa de um modelo fora do catálogo integrado, faturamento pelo provedor, um proxy interno, Ollama, LM Studio ou um serviço auto-hospedado compatível com OpenAI.
Para chat direto compatível, o PandaNpc envia a solicitação ao seu endpoint configurado em vez de substituir um modelo integrado. Seu provedor upstream continua controlando preços, retenção, limites de taxa, disponibilidade de modelos e uso aceitável.
Pré-requisitos e limites de segurança
Antes de adicionar um provedor, reúna:
- A chave de API do provedor ou token de autenticação local.
- A URL Base da API, normalmente terminando em
/v1para um serviço compatível com OpenAI. - O identificador exato do modelo aceito pela API.
- O contexto documentado e o limite máximo de saída, se você planeja substituir os padrões.
Use uma chave dedicada com as permissões mínimas necessárias e um limite de gastos onde o provedor oferecer suporte. Nunca coloque a chave em documentação, prompts de chat, capturas de tela, saída do console do navegador ou em um repositório Git.
Em um navegador da web, solicitações diretas estão sujeitas a CORS. O provedor deve permitir solicitações de https://pandanpc.com. Uma URL Base como http://localhost:11434/v1 refere-se ao computador que executa o navegador, não automaticamente à máquina remota PandaPaw. O aplicativo desktop pode ser mais adequado para endpoints locais porque não é limitado pelo CORS do navegador da mesma forma.
Passo 1: Abrir a Configuração de Modelos
Entre no PandaNpc e abra Model Configuration. Provedores e modelos são registros separados: o provedor armazena os detalhes de conexão e autenticação, enquanto cada modelo armazena o identificador e os limites enviados a essa conexão.
Se um provedor oficial já aparecer, configure ou copie-o em vez de criar um protocolo diferente. Para um novo gateway compatível com OpenAI, selecione Add Provider.
Passo 2: Adicionar o provedor
Preencha o formulário do provedor:
| Campo | O que inserir | Exemplo ou orientação |
|---|---|---|
| Display Name | Um rótulo visível para você | Company AI Gateway |
| Provider ID | Um identificador interno estável | company-openai |
| API Key | O segredo usado como token bearer | Valor emitido pelo provedor |
| Base URL | Raiz da API sem /chat/completions |
https://gateway.example.com/v1 |
| Protocol | O formato da API upstream | Escolha openai para chat completions compatível com OpenAI |
| Secret | Segundo segredo opcional | Deixe vazio, a menos que o provedor exija |
| Organization | Identificador de organização opcional | Somente quando exigido pelo provedor |
| Project | Identificador de projeto opcional | Somente quando exigido pelo provedor |
| Support content array | Se o conteúdo da mensagem pode usar arrays estruturados | Mantenha ativado para provedores que aceitam conteúdo multimodal moderno |
O PandaNpc remove barras finais da Base URL e anexa /chat/completions para a solicitação de chat direta compatível com OpenAI. Portanto, insira:
https://api.example.com/v1não:
https://api.example.com/v1/chat/completionsSalve o provedor antes de adicionar um modelo. Ao editar um provedor existente, um campo API Key ou Secret vazio significa "manter o valor configurado"; ele não expõe o segredo armazenado de volta ao formulário.
Passo 3: Adicionar um modelo
Escolha Add Model no provedor e preencha estes campos:
| Campo | Significado | Exemplo |
|---|---|---|
| Display Name | Rótulo legível para seleção | My Coding Model |
| Model Value | ID exato do modelo upstream | model-name-from-provider |
| Model Type | Mapeamento de capacidade/categoria do PandaNpc | Selecione um valor atual no formulário |
| Provider | Registro do provedor criado acima | Company AI Gateway |
| Context Window | Total de tokens suportados | Use o limite inteiro documentado pelo provedor |
| Max Tokens | Máximo de tokens de saída gerados | Use um valor positivo não maior que o limite do provedor |
Display Name pode ser alterado sem afetar a chamada de API. Model Value não pode ser adivinhado a partir de um nome comercial; copie-o da documentação da API do provedor ou do endpoint de lista de modelos.
Deixe Context Window e Max Tokens vazios quando não tiver certeza. Um padrão conservador é mais seguro do que declarar uma janela de contexto maior do que o servidor suporta. Esses campos são especialmente importantes para o PandaCode porque influenciam a compactação e o orçamento de saída.
Exemplos comuns de endpoints
Os padrões a seguir ilustram a forma da URL; disponibilidade e IDs de modelos dependem da sua instalação ou conta do provedor:
| Tipo de serviço | URL Base típica | Notas |
|---|---|---|
| API de nuvem compatível com OpenAI | https://provider.example.com/v1 |
Deve suportar Chat Completions em streaming e autenticação bearer |
| Ollama no computador de visualização | http://localhost:11434/v1 |
Inicie o endpoint compatível com OpenAI do Ollama; o uso no navegador pode exigir configuração de CORS |
| LM Studio no computador de visualização | http://localhost:1234/v1 |
Inicie o servidor local e selecione um ID de modelo carregado |
| Gateway de rede privada | https://ai.internal.example/v1 |
O cliente PandaNpc deve ser capaz de resolver e alcançar o host |
Não presuma que todo serviço que anuncia "compatível com OpenAI" implementa streaming, chamadas de ferramentas, imagens, campos de raciocínio ou respostas de erro idênticas. Teste os recursos exatos que seu fluxo de trabalho precisa.
Verificar o provedor e o modelo
Use um prompt de baixo custo e não sensível antes de confiar na configuração:
- Selecione o novo modelo em uma conversa nova.
- Envie
Reply with exactly: provider connected. - Confirme se a resposta é transmitida e se o painel do provedor registra a solicitação.
- Envie um breve acompanhamento para verificar o histórico da conversa.
- Se você precisar de ferramentas, imagens ou contexto longo, teste cada recurso separadamente.
Para um endpoint local, primeiro verifique-o fora do PandaNpc. Uma lista de modelos compatível com OpenAI geralmente está disponível com:
curl http://localhost:11434/v1/modelsUse a resposta apenas para confirmar a acessibilidade e o ID do modelo. Não coloque uma chave de API de produção diretamente no histórico do shell.
Usar modelos personalizados com o PandaCode
O PandaCode pode fornecer um fluxo de trabalho de codificação no estilo Claude Code enquanto usa um backend de modelo que você escolher, incluindo DeepSeek, Qwen, um gateway compatível com OpenAI ou um serviço interno. Após configurar o provedor e o modelo, selecione esse modelo para a conexão ou tarefa relevante do PandaCode.
O modelo deve suportar o padrão de interação exigido pelo mecanismo de codificação. Um provedor que funciona para chat simples pode ainda falhar em chamadas de ferramentas, streams de longa duração ou conteúdo estruturado. Veja AI models supported by PandaNpc para a diferença entre modelos de chat e mecanismos de codificação locais, e PandaPaw installation and commands para configuração remota de mecanismos.
Solução de problemas
Erro de autenticação `401` ou `403`
Crie uma nova chave de provedor, confirme que ela está ativa e insira-a novamente. Verifique se o serviço upstream exige uma organização, projeto ou método de autenticação diferente. Uma chave mascarada copiada de uma tela de edição não é o segredo original.
Endpoint ou modelo `404` não encontrado
Remova /chat/completions da Base URL configurada, pois o PandaNpc a anexa. Confirme se /v1 está presente quando necessário e se Model Value corresponde exatamente ao ID do modelo upstream. Um provedor pode retornar o mesmo 404 tanto para uma URL errada quanto para um modelo indisponível.
O navegador relata um erro de rede ou CORS
Abra o console de desenvolvedor do navegador apenas para identificar a origem bloqueada; não cole segredos lá. Configure o provedor para permitir https://pandanpc.com, use seu endpoint HTTPS ou use o aplicativo desktop do PandaNpc. As regras de conteúdo misto bloqueiam uma página HTTPS de chamar alguns endpoints HTTP simples.
Ollama ou LM Studio local não pode ser acessado
Certifique-se de que o servidor esteja rodando no mesmo computador que o cliente que faz a solicitação e ouvindo na interface e porta configuradas. Se o servidor de modelos estiver em outro computador, localhost está errado; use um nome de host ou IP privado acessível e proteja o serviço antes de expô-lo.
A resposta começa, mas para ou não tem conteúdo
Confirme se a API suporta Chat Completions em streaming e emite eventos padrão data:. Reduza Max Tokens, teste uma mensagem somente de texto e desative arrays de conteúdo estruturado somente se o provedor documentar que aceita conteúdo de string exclusivamente.
Sessões longas falham perto do limite de contexto
Reduza a Context Window configurada para o limite real suportado pelo provedor e reserve espaço para saída, instruções de sistema e resultados de ferramentas. Inicie uma nova sessão após alterar a configuração do modelo para que os novos limites sejam aplicados de forma consistente.
Para detalhes de cota de conta e fluxo de dados, leia PandaNpc accounts, plans, and API costs e a Privacy Policy.