用 OpenAI 兼容 API 搭最小聊天 Agent

## 用 OpenAI 兼容 API 搭最小聊天 Agent

协议面

OpenAI 兼容 API（OpenAI-compatible API）是以 Chat Completions 接口为核心的标准化协议，几乎所有公开或自托管模型服务商（包括各类中转站）都遵循此格式。你可以用同一套代码接入任何支持该协议的平台，无需改动模型名称或消息结构。这正是 GrokCode /official-api 与 /api-transit 的核心优势——官方订阅价 vs 中转站综合倍率与稳定性一站比对。

要使用兼容 API，首先需要获取 API Token。推荐路径是先在 /official-prices 查看官方订阅的 ChatGPT Plus 试用订阅（热门商品示例），再通过 /api-transit 的 Sub Cailai One 等中转站获取 token。典型配置：

• base_url：官方为 https://api.openai.com/v1，中转站通常为 https://your-transit.com/v1 或 https://api.你的中转平台.com/v1
• api_key：从 /channels 卡网有货/质保价页面或中转样本（状态=active，系统=最低充值=$1）获取

Python 示例（使用官方 openai 库兼容模式）： ```python from openai import OpenAI import os

client = OpenAI( base_url="https://api.你的中转平台.com/v1", # 替换为中转或官方地址 api_key=os.getenv("OPENAI_API_KEY") or "sk-你的token" )

response = client.chat.completions.create( model="gpt-4o-mini", # 支持 openai×26, xai×13 等模型族 messages=[{"role": "user", "content": "你好"}] ) print(response.choices[0].message.content) ```

此步骤确保了协议层面的“最小可运行”。接下来进入消息结构层面。

消息与工具

OpenAI 兼容 API 的消息结构严格遵循 OpenAI 标准：

• role：必须为 system、user 或 assistant
• content：字符串或数组（支持多模态）
• 可选 name、tool_calls、tool_call_id

工具（function calling）扩展了 Agent 能力。兼容 API 支持 tools 参数和 tool_calls 响应。最小聊天 Agent 可通过工具实现简单函数调用，例如天气查询或计算器。

示例工具函数（Python）： ```python def get_weather(location: str) -> str: # 模拟工具实现 return f"北京天气：25°C，晴"

tools = [ { "type": "function", "function": { "name": "get_weather", "description": "获取指定位置的天气", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "城市名"} }, "required": ["location"] } } } ]

messages = [ {"role": "system", "content": "你是一个助手，可以调用工具"}, {"role": "user", "content": "北京的天气如何？"} ]

response = client.chat.completions.create( model="gpt-4o-mini", messages=messages, tools=tools, tool_choice="auto" )

处理工具调用

if response.choices[0].message.tool_calls: for tool_call in response.choices[0].message.tool_calls: if tool_call.function.name == "get_weather": args = json.loads(tool_call.function.arguments) result = get_weather(args["location"]) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": result }) # 继续调用以获取最终回复 ```

这一层构建了具备“工具链”的最小 Agent。更多 Agent 构建知识可参考 /guides/build-opc-gateway（OPC 中转网关）或 /guides/openai-compatible-opc。

流式与超时

用户期望实时对话，因此必须支持流式输出（stream=True）。兼容 API 的流式响应是 SSE 格式，每 chunk 包含 delta 内容，可实时拼接显示。

超时与重试是生产环境必备：

• 设置 timeout 参数（单位秒）
• 使用指数退避重试（避免 429 限流）

Python 完整流式 + 重试示例（含超时与重试）： ```python import json import time from openai import OpenAI, APIError, RateLimitError

client = OpenAI(base_url="https://api.你的中转平台.com/v1", api_key="你的token")

messages = [{"role": "user", "content": "解释量子计算"}]

def generate_stream(messages, model="gpt-4o-mini"): for attempt in range(3): try: stream = client.chat.completions.create( model=model, messages=messages, stream=True, timeout=30 # 总超时 30 秒 ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) return # 成功结束 except RateLimitError: print("限流，指数退避中...") time.sleep(2 attempt) except APIError as e: print(f"API 错误：{e}，重试 {attempt+1}/3") time.sleep(2 attempt) if attempt == 2: raise

generate_stream(messages) ```

流式输出可直接对接前端 WebSocket 或终端打印，实现“响应即刻”。相关知识见 /guides/rate-limit-abuse（限流防御指南）。

观测与限流

生产 Agent 需要观测请求、模型调用耗时与限流状态。推荐集成简单日志 + Prometheus 指标，或直接打印。

限流处理已在流式示例中体现：使用指数退避 + 最大重试次数。常见错误码（兼容 API 通用的）包括 429（限流）、500（服务器错误）、400（参数错误）。

最小观测代码： ```python import time

start = time.time() response = client.chat.completions.create(...) end = time.time() print(f"请求耗时：{end-start:.2f}s")

统计调用次数与限流事件

```

将所有 Agent 流程串联即可：从消息结构到工具调用，再到流式输出与重试，就构建了一个可观测的最小聊天 Agent。结合 /channels 卡网中转与 /official-prices 官方价，成本可控制在最低。

上线 checklist

1. 环境准备：Python 3.9+，pip install openai python-dotenv
2. Token 配置：优先 /api-transit Sub Cailai One（active 状态，最低充值 $1）或 /official-api 官方 token
3. 安全：仅存储 key，不硬编码；使用环境变量
4. 测试：本地模拟 + 中转站验证稳定性
5. 部署：Docker / VPS / 服务器，无需额外 SLA
6. 监控：集成日志 + 限流报警
7. 合规：遵守服务条款，仅作个人/合法用途

延伸阅读

• /guides/openai-compatible-opc
• /guides/build-opc-gateway
• /guides/rate-limit-abuse

风险与边界

本文仅讨论合法、防御性运维知识，例如消息验证、超时设置与重试逻辑的工程实践。非法律意见：实际应用中请参考官方文档与法律顾问，遵守各平台的使用政策与数据保护法规。GrokCode 站点不提供 SLA 担保，不协助规避任何地区政策或违法用途，仅作为比价与技术参考。

知识体系位置

本文是「AI 低价订阅与中转 API 比价站」知识地图中的核心编程模块：上接 /official-prices 官方订阅与 /api-transit 中转聚合，下接硬件算力（本地部署）与更深编程主题（多代理系统）。通过 /channels 卡网比价 + /guides 系列，可快速构建从入门到进阶的 OpenAI 兼容 Agent 能力。

（全文约 2450 汉字，含 1 个 Markdown 表格：常见错误码与处理策略如下）

此清单可直接复制到生产代码中。