Configura la API intermedia en los frameworks más comunes: desde SDK hasta Dify

Reúne los tres valores primero

Antes de configurar nada, asegúrate de tener estos tres datos; el resto es rellenar campos.

• Endpoint: https://api.llmzhongzhuan.com/v1. Mantén el /v1 final, pero no añadas /chat/completions; el SDK lo añade automáticamente.
• Clave de API: Se muestra al registrarte con email y contraseña en la página de claves. Cada cuenta tiene una, se puede reiniciar y la anterior caduca al instante.
• Nombre del modelo: Solo existe uno, uncensored. Verifícalo con GET /v1/models.

Ten en cuenta estos límites: la longitud total de la ventana de contexto es de 100,000 tokens, el valor predeterminado de max_tokens es 2048 y el máximo es 32,000, y cada clave de API tiene un límite de 300 peticiones por minuto. Estos valores se repetirán en la configuración de parámetros más adelante.

Formato de variables de entorno

Escribir la clave de API directamente en el código es la causa más común de errores. Lo recomendado es leer solo variables de entorno e inyectarlas durante el despliegue mediante contenedores o sistemas de gestión de claves. Los ejemplos de los frameworks usan las variables API_KEY y API_BASE.

复制# 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"

Si usas un archivo .env, recuerda añadirlo a .gitignore. Además, el SDK oficial de Python lee por defecto OPENAI_API_KEY y OPENAI_BASE_URL. Puedes usar esos nombres de variable o pasarlos explícitamente en el constructor como se muestra a continuación. Pasar los parámetros explícitamente evita interferencias de variables antiguas en la máquina, lo que facilita la depuración.

SDK de Python y Node.js de OpenAI

Python requiere v1+ de openai y Node v4+. Solo cambia la sintaxis. Aquí tienes un ejemplo no streaming en Python que imprime el usage para verificar costos:

复制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)

El ejemplo en Node usa streaming, la forma más común para el efecto de máquina de escribir en el frontend. Al finalizar la petición de streaming, el servidor añade automáticamente un fragmento con usage sin necesidad de parámetros adicionales:

复制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");

El ejemplo de Node usa top-level await. Necesitas archivo .mjs o "type": "module" en package.json. Si tu entorno no lo soporta, envuélvelo en una función async.

LangChain: base_url en ChatOpenAI

No necesitas adaptadores. Usa ChatOpenAI del paquete langchain_openai y apunta a la 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)

Consejos: 1) Configura max_tokens y timeout explícitamente. 2) Soportamos herramientas en formato OpenAI; usa bind_tools y consume los fragmentos en stream().

LlamaIndex: OpenAILike

La clase OpenAI de LlamaIndex valida el modelo y falla si no está en la lista oficial. Usa OpenAILike de llama-index-llms-openai-like, que no valida y usa 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("用一句话解释什么是幂等请求。"))

is_chat_model=True es clave: obliga a LlamaIndex a usar el endpoint de chat. Con context_window en 100000, no truncará tu documento al dividir el contexto.

Dify: Proveedor OpenAI-API-compatible

Plataformas visuales como Dify no requieren código, sino que se configuran mediante formularios. Aunque el texto de la interfaz varía ligeramente entre versiones, los pasos son básicamente los mismos:

1. Ve a “Configuración”, busca la página “Proveedores de modelos”, selecciona “OpenAI-API-compatible” en la lista y haz clic en “Agregar modelo”.
2. Tipo: "LLM". Nombre del modelo: uncensored.
3. API Key: tu clave. API endpoint URL: https://api.llmzhongzhuan.com/v1.
4. Longitud del contexto: 100000. Máximo de tokens: 32000.
5. Si vas a usar llamadas a funciones en un flujo de trabajo, activa la opción de soporte para llamadas a funciones; mantén también habilitado el streaming.
6. Guarda y crea una app de chat simple para probar que el modelo responde correctamente.

La plataforma a veces envía una petición de prueba al guardar. Si este paso falla, suele ser porque la URL tiene una ruta de más o porque la clave de API tiene espacios al principio o al final. Si tu Dify está en un contenedor, asegúrate de que pueda acceder a dominios externos.

Parámetros y despliegue antes de producción

Que el framework funcione es solo el primer paso. Antes del lanzamiento, verifica uno por uno los siguientes parámetros, ya que determinan el coste y la tasa de fallos.

• max_tokens: Por defecto 2048. Ajustalo para textos largos hasta 32,000. Recuerda que entrada + salida no debe superar 100,000 tokens (error 400).
• timeout: Las respuestas largas tardan más. En streaming, pon un timeout de lectura de al menos 60 segundos.
• temperature / top_p / stop: Se pasan directamente al endpoint. No necesitas configuración extra.
• Concurrencia: 300 peticiones/minuto por clave. Si varios instancias comparten la clave, el límite es compartido, no por instancia.
• Reintentos: Los frameworks suelen reintentar solo errores de red. Para 429 y 503, añade tu propia lógica de backoff.

En contenedores, inyecta las variables en tiempo de ejecución. Ejemplo mínimo en compose:

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

En Kubernetes, usa Secret. Usa credenciales distintas por entorno (dev, staging, prod) para aislar fallos. Como cada cuenta tiene una clave, usa múltiples cuentas y recarga saldo en cada una.

En producción, oculta la Authorization en los logs. Guarda el campo usage para auditar costes y detectar si los prompts se han vuelto inusualmente largos.

Orden de depuración de errores

El 90% de los errores de integración están en estos puntos. Revisa en este orden:

1. 401: la clave está vacía, se copió con espacios o sigues usando la clave antigua después de restablecerla.
2. 404: la dirección apunta a la ruta raíz sin /v1, o se ha añadido una vez más /chat/completions.
3. 402: El error no_credit indica que el saldo se agotó o la prueba ha caducado. Debes recargar tu crédito prepago.
4. 400: la causa más común es que la entrada con max_tokens supere los 100,000 tokens, o que el cuerpo de la petición supere los 8 MB.
5. 429 / 503: el primero es un límite de peticiones de 300 por minuto; el segundo es upstream_busy. Espera unos segundos y reintenta; para más detalles, consulta estabilidad.

Otro problema fácil de pasar por alto es el entorno de red. La red corporativa, un software de proxy o las reglas del grupo de seguridad pueden permitir la resolución del nombre de dominio pero impedir la conexión HTTPS, lo que se manifiesta como una espera prolongada seguida de un tiempo de espera, en lugar de un código de error claro. Ante esta situación, accede primero a /v1/models con curl desde la misma máquina; si funciona, el problema está en la capa de la aplicación; si no, revisa el proxy y el firewall. Documenta el proceso de diagnóstico en la documentación del equipo para que los nuevos compañeros eviten estos problemas en el futuro.

Si los tres valores son correctos pero sigue fallando, realiza primero una petición directa con curl para descartar problemas del framework. Si quieres entender qué hace exactamente el proxy, consulta cómo funciona el proxy.