Conectar un SDK de OpenAI
Dirija un cliente compatible con OpenAI al gateway: modo endpoint para inspección completa o modo proxy para mayor comodidad.
Hay dos maneras de conectar clientes compatibles con OpenAI al gateway:
- Endpoint mode (recomendado): configure la URL base /v1 del gateway. Cada solicitud pasa por inspección completa.
- Proxy mode: configure el gateway como proxy HTTP de reenvío.
Endpoint mode#
Funciona con cualquier SDK compatible con OpenAI. Solo cambia la URL base.
Python#
from openai import OpenAI
client = OpenAI(
api_key="<provider-api-key>", # se pasa al backend
base_url="http://<gateway-host>:443/v1", # AI-FW gateway
default_headers={"X-Agent-ID": "my-agent-01"},
)
resp = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)Node.js#
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "<provider-api-key>",
baseURL: "http://<gateway-host>:443/v1",
defaultHeaders: { "X-Agent-ID": "my-agent-01" },
});
const resp = await client.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "Hello!" }],
});
console.log(resp.choices[0].message.content);curl#
curl http://<gateway-host>:443/v1/chat/completions -H "Content-Type: application/json" -H "X-Agent-ID: my-agent-01" -d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}]
}'Encabezados de solicitud#
| Encabezado | Propósito |
|---|---|
| Authorization: Bearer <key> | Autenticación del cliente y/o clave upstream, según el modo. |
| X-Agent-ID | Identidad del agente para seguimiento, enrutamiento y riesgo. |
| X-User-Id | Identidad del usuario (se prefieren las claims sub del token). |
| x-aifw-cache-refresh | Omite la consulta a caché para esta solicitud, pero permite guardar. |
Proxy mode#
Configure el gateway como proxy HTTP para clientes compatibles:
curl --proxy http://<gateway-host>:443 https://api.openai.com/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}]}'| Proxy mode | Comportamiento | Inspección |
|---|---|---|
| HTTP absolute-form | Se normaliza a /v1/* y se ejecuta el pipeline completo. | Completa |
| CONNECT tunnel (HTTPS) | Túnel TCP al backend incluido en allowlist. | Solo metadatos: TLS cifra el contenido de extremo a extremo. |
La CONNECT allow-list permite el host del backend predeterminado, backends de modelos registrados y hosts añadidos en Settings -> Forward Proxy -> Allowed Tunnel Hosts. Los demás devuelven 403. El proxy de reenvío se puede deshabilitar.
Para inspeccionar contenido, use endpoint mode. CONNECT tunnel está cifrado de extremo a extremo; solo se registran metadatos.
Streaming#
stream: true funciona como con cualquier backend OpenAI. buffered inspecciona la respuesta completa antes de entregarla; stream transmite tokens en vivo y termina el flujo ante una infracción.
Solución de problemas#
- 401: compruebe modo de autenticación y API key.
- model_not_registered: registre el modelo o desactive Reject Unregistered Models.
- model_disabled: habilite el modelo en Model Inventory.
- Sin inspección de contenido: use endpoint mode, no CONNECT tunnel.