用途:在后端或 worker 中调用 OpenAI 模型,按项目既有风格选择 Chat Completions 或较新的 Responses API,并使用官方 SDK。
主要能力:Chat Completions(POST /v1/chat/completions)、Responses API(项目已迁移时)、流式输出、工具/函数调用、结构化输出(response_format / JSON schema,在版本与模型支持时)。
用法要点:API key 仅放后端,认证头 Authorization: Bearer <OPENAI_API_KEY>,默认 base URL 为 https://api.openai.com/v1;Azure OpenAI 或代理的 base URL 与认证不同,沿用项目配置。Model ID 固定于 config/env。角色含 system/user/assistant/tool;读取 finish_reason(stop、tool_calls、length 等)。工具调用时声明 JSON Schema 参数,服务端执行 tool_calls,追加 role 为 tool 且带 tool_call_id 的消息并继续循环,执行副作用前校验参数,遵循最小权限,破坏性操作需人工确认或幂等。流式用 stream: true 遍历 chunk 的 delta.content 转发,避免全量缓冲,处理断连。
限制:401/403 属 key/项目问题,不盲目重试;429 退避并关注限流/配额;5xx 有限重试或回退;length/context 超限需显式截断历史。监控 usage 与成本,按环境分离 key 与项目。Ollama 等代理可能暴露 /v1/chat/completions,Claude/Anthropic 是另一套 API,勿盲目复用 payload。避免前端暴露 key、无上限工具循环、对 schema 校验错误重试、只靠 JSON mode 不解析校验、混用 Azure 与 api.openai.com。