Guia de configuração do gateway de IA da Cloudflare: centralizando os serviços de chamada de API de IA

Com a popularidade dos LLMs (Large Language Models) e de vários serviços de IA, está se tornando cada vez mais comum que os desenvolvedores integrem esses recursos em seus aplicativos. No entanto, chamadas diretas como OpenAIeHugging Face e os pontos de extremidade de API de outros provedores de serviços, muitas vezes apresentando uma série de desafios de gerenciamento e O&M:

• Custos não transparentesO que é: À medida que o volume de solicitações de API cresce, os custos associados também aumentam. No entanto, muitas vezes é difícil para os desenvolvedores rastrear com precisão quais chamadas específicas estão consumindo mais recursos e quais são solicitações inválidas ou redundantes, o que dificulta a otimização dos custos.
• flutuação de desempenhoEm períodos de alta simultaneidade, o tempo de resposta da API do serviço de IA pode ser prolongado, ou até mesmo podem ocorrer tempos limite ocasionais, o que afeta diretamente a experiência do usuário e a estabilidade do aplicativo.
• Falta de monitoramentoA falta de uma plataforma unificada para monitorar as principais métricas, como os recursos usados com mais frequência pelos usuários, os prompts (prompts) que funcionam melhor, o tipo e a frequência de solicitações erradas etc., deixa a otimização do serviço sem suporte de dados.
• Restrições de endereço IP e problemas de reputaçãoAlguns serviços de IA têm restrições ou políticas rigorosas sobre o endereço IP do qual as solicitações são originadas. Iniciar uma chamada usando um endereço IP compartilhado ou de má reputação pode fazer com que a solicitação falhe ou até mesmo afetar a qualidade do resultado do modelo.

Para enfrentar esses desafios.Cloudflare lançado AI Gateway Serviço. Essa é uma camada de proxy inteligente disponível gratuitamente que fica entre o aplicativo e o serviço de IA de back-end, concentrando-se no gerenciamento, no monitoramento e na otimização das solicitações de IA, em vez de executar o próprio cálculo de IA.

Cloudflare AI Gateway O principal valor está no fornecimento de análise e registro unificados, cache inteligente, limitação de taxa e novas tentativas automáticas. Ao rotear o tráfego de solicitações de IA para AI GatewayAlém disso, os desenvolvedores podem obter um ponto de controle centralizado que aborda com eficácia os pontos problemáticos acima. Em particular, seus nós de rede global ajudam a atuar como retransmissores confiáveis, aliviando os problemas causados por restrições de endereço IP ou localização geográfica.

A seguir, demonstraremos como configurar e usar o Cloudflare AI Gateway.

Etapa 1: criar uma instância do AI Gateway

O processo de configuração é simples, desde que se tenha um Cloudflare Conta (gratuita para criar se ainda não estiver registrada).

1. Fazer login no console da Cloudflare: Acesso dashboard.cloudflare.com.
2. Navegar para IALocalize e clique na opção "AI" no menu à esquerda.
3. Selecione AI GatewayNo submenu AI, clique em "AI Gateway".
4. Criando um gatewayClique no botão "Create Gateway" (Criar Gateway) em destaque na página.
5. Gateways nomeadosAtribua um nome claro ao gateway, por exemplo. my-app-gatewayEsse nome se tornará parte do URL dos pontos de extremidade de API subsequentes. Esse nome se tornará parte do URL dos endpoints de API subsequentes.
6. (Opcional) Adicionar descriçãoInformações descritivas podem ser adicionadas para facilitar o gerenciamento subsequente.
7. Confirmação da criaçãoApós preencher o nome e a descrição, clique em Confirm Creation (Confirmar criação).

Após a criação bem-sucedida, o sistema exibe a página de detalhes do gateway. As principais informações são URL do ponto de extremidade do gateway(URL do endpoint do gateway), certifique-se de documentá-lo. O formato básico é o seguinte:

https://gateway.ai.cloudflare.com/v1/<ACCOUNT_TAG>/<GATEWAY_NAME>/<PROVIDER>

• <ACCOUNT_TAG>::Cloudflare O identificador exclusivo da conta, que é preenchido automaticamente.
• <GATEWAY_NAME>Nome do gateway: O nome definido para o gateway na etapa anterior, por exemplo. my-app-gateway.
• <PROVIDER>: o identificador do provedor de serviços de IA de destino, por exemplo, o openai, workers-ai, huggingface etc. Isso indica AI Gateway Para qual serviço de back-end encaminhar a solicitação.

Etapa 2: Integrar o AI Gateway ao aplicativo

Esta é a etapa principal: o código do aplicativo precisa ser modificado para substituir o URL básico que acessa diretamente a API do serviço de IA pelo URL obtido na etapa anterior. Cloudflare AI Gateway URL.

Observações importantesURL de base: somente a parte do URL de base precisa ser substituída. O caminho da solicitação, os parâmetros de consulta, os cabeçalhos da solicitação (incluindo a chave da API) etc. devem permanecer inalterados.AI Gateway O cabeçalho da solicitação que contém a chave da API é passado com segurança para o provedor de serviços de IA final.

Exemplo 1: usando o SDK da OpenAI em um aplicativo Python

Supondo que a chamada direta original para OpenAI O código da API é o seguinte:

# --- 原始代码 (直接调用 OpenAI) ---
import openai
import os
# 从环境变量加载 OpenAI API Key
client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
# 默认 base_url 指向 https://api.openai.com/v1
try:
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "你好，世界！"}]
)
print("OpenAI Direct Response:", response.choices[0].message.content)
except Exception as e:
print(f"Error: {e}")

Modificado por AI Gateway Enviar solicitação:

# --- 修改后代码 (通过 Cloudflare AI Gateway) ---
import openai
import os
# Cloudflare 账户 Tag 和 网关名称 (替换为实际值)
cf_account_tag = "YOUR_CLOUDFLARE_ACCOUNT_TAG"
cf_gateway_name = "my-app-gateway"
# 构造指向 OpenAI 的 AI Gateway URL
# 注意末尾的 /openai 是提供商标识
gateway_url = f"https://gateway.ai.cloudflare.com/v1/{cf_account_tag}/{cf_gateway_name}/openai"
# OpenAI API Key 保持不变，从环境变量加载
api_key = os.environ.get("OPENAI_API_KEY")
# 核心修改：在初始化 OpenAI 客户端时传入 base_url 参数
client = openai.OpenAI(
api_key=api_key,
base_url=gateway_url  # 指向 Cloudflare AI Gateway
)
try:
# 请求的模型、消息等其他参数保持不变
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "你好，世界！(通过 Gateway)"}]
)
print("Via AI Gateway Response:", response.choices[0].message.content)
except Exception as e:
print(f"Error hitting Gateway: {e}")

A principal mudança está na inicialização OpenAI Quando o cliente recebe o base_url especifica o parâmetro AI Gateway URL.

Exemplo 2: Usando a API fetch em JavaScript (Node.js ou navegador)

Supondo que o código original use fetch chamada direta OpenAI::

// --- 原始代码 (直接 fetch OpenAI) ---
const apiKey = process.env.OPENAI_API_KEY; // 或其他获取方式
const openAIBaseUrl = "https://api.openai.com/v1";
fetch(`${openAIBaseUrl}/chat/completions`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`
},
body: JSON.stringify({
model: "gpt-3.5-turbo",
messages: [{"role": "user", "content": "Hello from fetch!"}]
})
})
.then(res => res.json())
.then(data => console.log("OpenAI Direct Fetch:", data.choices[0].message.content))
.catch(err => console.error("Error:", err));

Modificado para adotar AI Gateway Enviar solicitação:

// --- 修改后代码 (通过 AI Gateway fetch) ---
const apiKey = process.env.OPENAI_API_KEY;
const cfAccountTag = "YOUR_CLOUDFLARE_ACCOUNT_TAG"; // 替换为实际值
const cfGatewayName = "my-app-gateway"; // 替换为实际值
// 构造 AI Gateway URL
const gatewayBaseUrl = `https://gateway.ai.cloudflare.com/v1/${cfAccountTag}/${cfGatewayName}/openai`;
// 核心修改：替换请求 URL 的基础部分
fetch(`${gatewayBaseUrl}/chat/completions`, { // URL 指向 Gateway
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}` // API Key 仍在 Header 中发送
},
body: JSON.stringify({ // 请求体不变
model: "gpt-3.5-turbo",
messages: [{"role": "user", "content": "Hello from fetch via Gateway!"}]
})
})
.then(res => res.json())
.then(data => console.log("Via AI Gateway Fetch:", data.choices[0].message.content))
.catch(err => console.error("Error hitting Gateway:", err));

Independentemente da linguagem de programação ou da estrutura usada (por exemplo LangChain, LlamaIndex etc.), a ideia básica da integração é a mesma: encontrar o local onde o endpoint da API do serviço de IA ou o URL de base está configurado e substituí-lo pelo Cloudflare AI Gateway URL.

Depois de concluir as alterações de código e implantar o aplicativo, todas as solicitações para o serviço de IA de destino fluirão por meio do AI Gateway.

Etapa 3: Utilize a funcionalidade embutida do AI Gateway

voltar (ou ir) Cloudflare no console AI Gateway Página de administração, que permite que você observe e aproveite os recursos que ela oferece:

• AnálisesGráfico de desempenho: fornece gráficos visuais sobre as principais métricas, como volume de solicitações, taxa de sucesso, distribuição de erros, uso de token, custo estimado, latência (P95/P99) e muito mais. Isso ajuda a identificar rapidamente os gargalos de desempenho e as exceções de custo.
• RegistrosLogs de solicitação: fornece logs de solicitação detalhados, registrando informações como carimbos de data e hora, códigos de status, modelos de destino, metadados parciais de solicitação/resposta, tempo decorrido, status do cache e assim por diante, para cada solicitação. É uma ferramenta importante para a solução de problemas e análise do comportamento do usuário.
• Armazenamento em cacheCache: O cache pode ser ativado na página "Settings" (Configurações) do gateway. O armazenamento em cache pode ser ativado definindo o TTL (Time-To-Live)Por exemplo, 1 hora (3600 segundos).AI Gateway As respostas a solicitações idênticas (com palavras de prompt, modelos etc. idênticos) podem ser armazenadas em cache. Durante o período de validade do TTL, as solicitações idênticas subsequentes serão tratadas diretamente pelo Gateway Retorna resultados armazenados em cache, é extremamente responsivo eNão consome recursos de token ou computação de provedores de serviços de IA de back-end. Isso é particularmente eficaz para cenários em que há solicitações repetidas, como conteúdo gerado por IA (por exemplo, descrições de produtos), e pode reduzir significativamente o custo e a latência.
• Limitação de taxaRegras de limitação de taxa também podem ser configuradas na página Settings (Configurações). Você pode limitar a frequência de solicitações com base em endereços IP ou cabeçalhos de solicitação personalizados (por exemplo, passando uma ID de usuário ou uma chave de API específica). Por exemplo, você pode definir "Allow up to 20 requests per minute for a single IP address" (Permitir até 20 solicitações por minuto para um único endereço IP). Isso ajuda a evitar ataques mal-intencionados ou o uso indevido de recursos devido a erros de programação.

valor estratégico

Para desenvolvedores e equipes que precisam integrar e gerenciar um ou mais serviços de IA, oCloudflare AI Gateway oferece uma solução centralizada e fácil de gerenciar. Ele não só aborda os desafios de custo, desempenho e monitoramento normalmente associados às chamadas diretas à API, como também oferece uma camada adicional de otimização e proteção por meio de recursos como cache e limitação de taxa. Em vez de os desenvolvedores criarem e manterem proxies, cache e sistemas de monitoramento semelhantes por conta própria, oAI Gateway Redução significativa da complexidade e da carga de trabalho. À medida que os aplicativos de IA se aprofundam, o gerenciamento unificado com esses serviços de gateway é essencial para manter a robustez do sistema, controlar os custos operacionais e a flexibilidade futura para expansão.