Configurando a API de roteamento nos principais frameworks: de SDK a Dify

Reúna os três valores necessários

Antes de configurar qualquer framework, certifique-se de ter esses três valores. O restante da configuração consiste apenas em preenchê-los.

• Endpoint: https://api.llmzhongzhuan.com/v1. Mantenha o /v1, mas não adicione /chat/completions; o SDK faz isso.
• Chave: Disponível imediatamente após o registro na página de obtenção de chave. Cada conta possui uma chave, que pode ser redefinida, invalidando a anterior instantaneamente.
• Modelo: apenas uncensored. Confirme com GET /v1/models.

Atenção aos limites: janela de contexto de 100.000 tokens, max_tokens padrão 2.048 e máximo 32.000, e 300 requisições por minuto por chave. Esses valores serão usados nas configurações de parâmetros.

Formato das variáveis de ambiente

Hardcode é erro comum. Use variáveis de ambiente. Usaremos API_KEY e API_BASE nos exemplos.

复制# Linux / macOS：写进 ~/.zshrc 或 .env 加载脚本
export API_KEY="替换为你的密钥"
export API_BASE="https://api.llmzhongzhuan.com/v1"

# Windows PowerShell（仅当前会话）
$env:API_KEY = "替换为你的密钥"
$env:API_BASE = "https://api.llmzhongzhuan.com/v1"

Adicione .env ao .gitignore. O SDK Python lê OPENAI_API_KEY e OPENAI_BASE_URL. Você pode passar explicitamente para evitar conflitos.

SDK Python e SDK Node.js da OpenAI

O Python precisa da versão 1 ou superior do openai, e o Node precisa da versão 4 ou superior. A diferença entre eles é apenas a sintaxe; ao criar o cliente, basta passar o endereço e a chave. Vamos começar com a chamada não streaming em Python, imprimindo o usage para facilitar a conferência dos custos:

复制import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "写一条 20 字以内的发布公告标题。"}],
    max_tokens=100,
)
print(resp.choices[0].message.content)
print(resp.usage)

O exemplo Node.js usa streaming, ideal para efeitos de digitação. O servidor envia automaticamente um fragmento com usage no final; não são necessários parâmetros extras:

复制import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.API_BASE ?? "https://api.llmzhongzhuan.com/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "列出三个命名服务端日志字段的好习惯。" }],
  stream: true,
  max_tokens: 300,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
process.stdout.write("\n");

O exemplo em Node usa await no nível superior, o que requer um arquivo .mjs ou a configuração "type": "module" no package.json. Se o seu ambiente de execução não suportar, envolva o código em uma função async.

LangChain: base_url no ChatOpenAI

LangChain usa langchain_openai. Instancie ChatOpenAI e defina base_url.

复制import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    temperature=0.7,
    max_tokens=500,
    timeout=60,
)

print(llm.invoke("把“服务已降级”改写成对用户友好的一句话。").content)

Defina max_tokens e timeout explicitamente. Para tools, use bind_tools; consuma em stream().

LlamaIndex: OpenAILike

A classe OpenAI padrão falha com modelos customizados. Use llama-index-llms-openai-like e OpenAILike com api_base.

复制import os
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    model="uncensored",
    api_base=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    is_chat_model=True,
    context_window=100000,
    max_tokens=500,
)

print(llm.complete("用一句话解释什么是幂等请求。"))

Use is_chat_model=True para usar o endpoint de chat. context_window=100000 evita truncamento.

Dify: Provedor OpenAI-API-compatible

Plataformas visuais como o Dify usam formulários. O processo é consistente entre versões:

1. Vá para "Configurações" > "Provedores de Modelo", selecione "OpenAI-API-compatible" e clique em "Adicionar Modelo".
2. Tipo: LLM. Modelo: uncensored.
3. Chave: sua API Key. Endpoint: https://api.llmzhongzhuan.com/v1.
4. Comprimento do contexto do modelo: 100000. Limite máximo de tokens: 32000.
5. Ative a opção de suporte a chamada de funções se for usar ferramentas no fluxo de trabalho. Mantenha o streaming habilitado.
6. Salve, crie um app de chat simples, selecione o modelo e envie uma mensagem para testar a resposta.

O Dify pode enviar uma requisição de teste ao salvar. Se falhar, verifique se há caminhos extras no endpoint ou espaços na chave. Se o Dify está em container, garanta que ele tenha acesso à internet.

Parâmetros e configuração para produção

Fazer o framework rodar é apenas o primeiro passo. Verifique estes parâmetros antes de ir para produção para controlar custos e falhas.

• max_tokens: Padrão 2048. Aumente explicitamente para textos longos, até 32.000. O total (input + output) não deve exceder 100.000 tokens, ou você receberá erro 400.
• timeout: Saídas longas demoram mais. Para streaming, defina read_timeout para 60s+. Para não-streaming, estime pelo tempo máximo de saída.
• temperature / top_p / stop: parâmetros de amostragem padrão são passados diretamente. Valores definidos no framework são aplicados sem necessidade de chave extra.
• Concorrência: limite de 300 requisições por minuto por chave. Se múltiplas instâncias usam a mesma chave, o limite é compartilhado; não planeje 300 requisições para cada instância.
• Retentativa: Retentativas padrão podem não cobrir 429 e 503. Adicione lógica de backoff conforme descrito no guia de estabilidade.

Em containers, a lógica é a mesma: não inclua chaves na imagem. Injete-as na inicialização. Exemplo mínimo em compose:

复制# docker-compose.yml 片段
services:
  app:
    image: your-app:latest
    environment:
      API_BASE: https://api.llmzhongzhuan.com/v1
      API_KEY: ${API_KEY}   # 从宿主机环境或 .env 读取，不写进镜像

No Kubernetes, use Secret References. Separe contas/chaves por ambiente (dev, staging, prod) para evitar que vazamentos ou esgotamento de saldo em um ambiente afetem a produção. Como cada conta tem uma chave, use contas separadas e pré-carregue saldos.

Logs: em modo debug, cabeçalhos completos (incluindo Authorization) são impressos. Desative logs de debug em produção ou filtre a chave. Registre o campo usage para conferência de fatura e detecção de prompts longos.

Ordem de resolução de erros

90% dos problemas de integração ocorrem em poucos pontos. Verifique na seguinte ordem:

1. 401: a chave está vazia, há espaços ao copiar ou você ainda está usando a chave antiga após a redefinição.
2. 404: o endereço está como o caminho raiz sem /v1 ou você adicionou extra /chat/completions.
3. 402: o código de erro é no_credit, o que significa que o saldo acabou ou o teste expirou; é necessário recarregar o crédito pré-pago.
4. 400: a causa comum é que o input com max_tokens excedeu 100,000 ou o corpo da requisição ultrapassou 8 MB.
5. 429 / 503: o primeiro é o limite de 300 requisições por minuto; o segundo é upstream_busy. Aguarde alguns segundos e tente novamente. Veja a prática de estabilidade para mais detalhes.

Outro problema frequentemente negligenciado é o ambiente de rede. A rede interna da empresa, software de proxy ou regras de grupo de segurança podem permitir a resolução do nome de domínio, mas impedir a conexão HTTPS, resultando em longos tempos de espera seguidos de timeout, em vez de um código de erro explícito. Ao encontrar isso, acesse /v1/models com curl na mesma máquina. Se funcionar, o problema está na camada de aplicação; se não funcionar, verifique o proxy e o firewall. Registre o processo de solução de problemas na documentação da equipe para que novos colegas evitem esse problema na próxima vez.

Se os três valores estão corretos e ainda falha, faça uma solicitação direta com curl primeiro para excluir problemas da própria estrutura. Se quiser entender o que exatamente o proxy faz, consulte o princípio do proxy.