《WaLiAPI - 本地 LLM API 网关》第3-1节：多协议转换引擎

作者：小傅哥
博客：https://bugstack.cn (opens new window)

沉淀、分享、成长，让自己和他人都能有所收获！😄

大家好，我是技术UP主小傅哥。

前两节我们完成了 API 网关的基础功能——渠道分发、安全扫描、前端页面。现在开始一个关键的新能力：让 WaLiAPI 不仅兼容 OpenAI 格式，还能兼容 Anthropic Claude 和 OpenAI Responses 两种协议。这就是多协议转换引擎的核心使命。

一、本章诉求

1. 理解为什么需要多协议转换——而不是让下游应用各自适配
2. 实现 Anthropic Messages API 的双向转换（请求/响应）
3. 实现 OpenAI Responses API 的双向转换（请求/响应）
4. 实现 Anthropic 和 Responses 的 SSE 流式转换
5. 在 handlers 和 router 层注册新路由
6. 增强 adaptor 层的 sanitize_messages 处理

二、为什么需要多协议转换？

2.1 现状问题

当前 WaLiAPI 只支持 OpenAI Chat Completions 格式。但实际场景中：

• Anthropic Claude 使用 messages 端点、x-api-key 认证、content 数组格式（含 text/tool_use/tool_result block）
• OpenAI Responses API 使用 input 替代 messages、instructions 替代 system、扁平化工具定义

下游应用（Cursor、Claude Desktop、MCP Client 等）往往直接使用供应商原生协议。如果每个应用都自己做格式适配，那是 N×M 的复杂度。

2.2 网关层统一转换

WaLiAPI 的选择是：在网关层做协议转换，对外暴露三种端点，内部统一走 OpenAI 格式。

┌─────────────────────────────────────────────────────┐
│              下游应用（三种协议）                      │
│  Cursor/OpenAI SDK ──→ /v1/chat/completions          │
│  Claude Desktop ────→ /v1/messages                  │
│  MCP Client ────────→ /v1/responses                  │
└───────────────────────┬─────────────────────────────┘
                        │ 三种请求格式
┌───────────────────────▼─────────────────────────────┐
│              WaLiAPI Protocol 层                      │
│  anthropic_to_openai() ──→ OpenAI 格式               │
│  responses_to_openai()  ──→ OpenAI 格式               │
│  Chat Completions 直接 → OpenAI 格式                  │
└───────────────────────┬─────────────────────────────┘
                        │ 统一 OpenAI 格式
┌───────────────────────▼─────────────────────────────┐
│              Proxy 层（渠道分发 + 重试）               │
│  dispatcher → adaptor → upstream                      │
└───────────────────────┬─────────────────────────────┘
                        │ OpenAI 格式响应
┌───────────────────────▼─────────────────────────────┐
│              Protocol 层反向转换                       │
│  openai_to_anthropic() ──→ Anthropic 格式            │
│  openai_to_responses()  ──→ Responses 格式            │
│  Chat Completions 直接 → OpenAI 格式                  │
└───────────────────────┬─────────────────────────────┘
                        │ 三种响应格式
┌───────────────────────▼─────────────────────────────┐
│              下游应用收到对应格式的响应                  │
└─────────────────────────────────────────────────────┘

核心收益：

• 下游应用零改动就能接入 WaLiAPI
• 内部 Proxy 只需处理一种格式（OpenAI），代码简洁
• 新增协议只需加转换层，不影响核心 Proxy 逻辑