What · 是什么
4 种协议：Anthropic Messages / OpenAI Chat Completions / OpenAI Responses / Bedrock SigV4，统一 CompletionsWithCtx 接口
抽象统一 LLMClient 接口，核心方法 CompletionsWithCtx，屏蔽不同厂商协议差异
4 种内置协议：anthropic（Messages API，基于 anthropic-sdk-go）、openai（Chat Completions，端点 /v1/chat/completions，基于 openai-go/v3）、openai-responses（OpenAI Responses API，端点 /v1/responses，URL 自动补后缀）、anthropic-bedrock（AWS SigV4 签名，模型名进 URL 路径）
OpenAI 系协议流式响应走 ssestream（SSE 流解析）
Responses API 为无状态设计：每个请求携带全量对话历史，服务端不维护会话状态
协议选择可通过 PROTOCOL 环境变量或 USE_ANTHROPIC 兼容开关控制
Why · 为什么
原理 · Principle
不同厂商 API 形态差异大（Messages 与 Chat Completions 的消息结构、工具调用格式不同），统一接口降低接入成本
协议可插拔：新增厂商只需实现 LLMClient 接口，扩展点清晰
Responses API 无状态设计简化服务端实现，代价是客户端需自行携带全量历史
How · 怎么做
显式指定：export OCR_LLM_PROTOCOL=openai（或 anthropic/openai-responses/anthropic-bedrock）
Claude 兼容习惯：USE_ANTHROPIC=true 走 anthropic 协议（Messages API）
AWS Bedrock：协议选 anthropic-bedrock，配置 AWS 凭证完成 SigV4 签名，模型名放入 URL 路径
openai-responses：base URL 后自动补 /v1/responses 后缀，无需手动拼路径
OpenAI 兼容网关（vLLM/OneAPI 等）：选 openai 协议指向 /v1/chat/completions
自定义 provider 时按端点能力选协议：OpenAI 兼容端点选 openai，Anthropic 兼容端点选 anthropic
案例 · Cases
| 代表性案例 |
|---|
| OpenAI 兼容网关：openai 协议 + /v1/chat/completions 端点 |
| Claude 官方或兼容端点：anthropic 协议 Messages API |
| AWS Bedrock 上部署的模型：anthropic-bedrock 协议 + SigV4 签名 |
| 新项目接入 Responses API：openai-responses，享受无状态端点简化 |
反模式 · Anti-patterns
- 忘记 Responses API 无状态特性：把短历史当会话用，模型丢失前文；每请求必须带全量历史
- Bedrock 选错协议：不用 anthropic-bedrock 就没有 SigV4 签名，请求 403
- openai-responses 手动拼接 URL：协议已自动补 /v1/responses 后缀，再拼会重复路径
- 流式响应当普通 JSON 解析：SSE 流需按 ssestream 处理，直接解析会截断或失败
正反实例论证 · Evidence
正例 · Pro
openai 协议对接 OpenAI 兼容端点
export OCR_LLM_PROTOCOL=openaiexport OCR_LLM_URL=https://api.openai.com/v1export OCR_LLM_MODEL=gpt-4o走 /v1/chat/completions（openai-go/v3），流式响应经 ssestream 正确解析，OpenAI 兼容网关（vLLM/OneAPI 等）同样适用。
反例 · Con
anthropic 协议打 OpenAI 端点
export OCR_LLM_PROTOCOL=anthropicexport OCR_LLM_URL=https://api.openai.com/v1Messages API（anthropic-sdk-go）与 Chat Completions 的消息结构、工具调用格式不兼容，请求返回 400 格式错误。协议必须与端点匹配。
正例 · Pro
anthropic 协议对接 Claude 端点
export OCR_LLM_PROTOCOL=anthropicexport OCR_LLM_URL=https://api.anthropic.com走 Messages API，Claude 官方端点或 Anthropic 兼容端点均可；USE_ANTHROPIC=true 可作兼容开关。
反例 · Con
Bedrock 端点忘了 SigV4 签名
export OCR_LLM_PROTOCOL=anthropic# 目标其实是 AWS Bedrock 端点对 Bedrock 端点必须选 anthropic-bedrock 协议做 SigV4 签名（模型名进 URL 路径）；选 anthropic 无签名，请求 403。
正例 · Pro
openai-responses 协议自动补后缀
export OCR_LLM_PROTOCOL=openai-responsesexport OCR_LLM_URL=https://api.openai.comURL 自动补 /v1/responses 后缀，无需手动拼路径；注意 Responses API 无状态，每个请求需携带全量对话历史。
反例 · Con
手动拼接 /v1/responses 造成重复路径
export OCR_LLM_PROTOCOL=openai-responsesexport OCR_LLM_URL=https://api.openai.com/v1/responses协议已自动补 /v1/responses 后缀，再手动拼接路径重复，请求 404。