Conectar um SDK OpenAI
Direcione clientes compatíveis com OpenAI ao gateway: endpoint mode para inspeção completa ou proxy mode.
Há duas formas de conectar clientes compatíveis com OpenAI ao gateway:
- Endpoint mode (recomendado): configure a URL base /v1 do gateway. Cada solicitação passa por inspeção completa.
- Proxy mode: configure o gateway como proxy HTTP de encaminhamento.
Endpoint mode#
Qualquer SDK compatível com OpenAI funciona; só muda a URL base.
Python#
from openai import OpenAI
client = OpenAI(
api_key="<provider-api-key>", # encaminhada ao 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!"}]
}'Cabeçalhos#
| Cabeçalho | Finalidade |
|---|---|
| Authorization: Bearer <key> | Autenticação do cliente e/ou chave upstream conforme o modo configurado. |
| X-Agent-ID | Identidade do agente para acompanhamento, roteamento e risco. |
| X-User-Id | Identidade do usuário; claims sub do token têm preferência. |
| x-aifw-cache-refresh | Ignora consulta ao cache, mas permite gravar. |
Proxy mode#
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 | Comportamento | Inspeção |
|---|---|---|
| HTTP absolute-form | Normalizado para /v1/* e passa pelo pipeline completo. | Completa |
| CONNECT tunnel (HTTPS) | Túnel TCP para backend permitido. | Apenas metadados; TLS cifra ponta a ponta. |
A CONNECT allow-list permite host backend padrão, backends de modelos registrados e hosts adicionados em Settings -> Forward Proxy -> Allowed Tunnel Hosts. Outros retornam 403. O proxy pode ser desabilitado.
O túnel HTTPS não é inspecionado
Use endpoint mode para inspecionar conteúdo. CONNECT tunnel é criptografado ponta a ponta; só metadados são registrados.
Streaming#
stream: true funciona como em qualquer backend OpenAI. buffered inspeciona a resposta inteira antes da entrega; stream transmite tokens ao vivo e termina diante de violação.
Solução de problemas#
- 401: confira autenticação e API key.
- model_not_registered: registre o modelo ou desative Reject Unregistered Models.
- model_disabled: habilite o modelo em Model Inventory.
- Sem inspeção: use endpoint mode, não CONNECT tunnel.