ds2api 如何用一套接口兼容三大协议
作者:carzy2026.11.17 03:18浏览量:0简介:这篇文章拆解 ds2api 的协议适配层,说明多协议入口、统一内部表示和响应回写的协作方式。文中给出 OpenAI、Claude、Gemini 三套客户端的配置与流式代码,附 curl 验证命令、常见报错排查表和上线前的稳定性与合规检查清单,读者可以按步骤接入并快速定位问题。
先说明一点:文中路径、变量名和映射表都是示意。你实际部署的 ds2api 版本可能有不同的字段和路径,上线前以它的文档和实际响应为准。
一、设计架构
ds2api 位于客户端和模型之间,是一个协议适配层。它的请求链路可以拆成五步:
- 客户端按自己熟悉的协议发起请求,例如 OpenAI SDK 调用
/v1/chat/completions。 - 协议入口根据路由选择对应的解析逻辑,把请求体转换为内部结构。
- 适配层查找模型映射表,把客户端传入的模型名转到后端模型。
- 后端调用完成,返回的文本、工具调用和用量信息被统一保存。
- 适配层按入口协议重新组装响应,写回客户端。
这样设计的好处是,转换逻辑集中在一处。接入的客户端越多,需要维护的转换规则只增长一份,不会按”客户端乘以协议”的组合数增长。
二、三套入口与内部表示
1. 三套协议入口
| 协议 | 典型路径 | 鉴权头 | 流式方式 |
|---|---|---|---|
| OpenAI | /v1/chat/completions |
Authorization: Bearer <key> |
SSE,data: 行,结束标志 data: [DONE] |
| Claude | /v1/messages |
x-api-key: <key>,需带 anthropic-version |
SSE,带事件名,如 message_start、content_block_delta、message_stop |
| Gemini | /v1beta/models/{model}:generateContent |
x-goog-api-key: <key> |
路径为 :streamGenerateContent,加 alt=sse 时为 SSE,否则为连续的 JSON 对象 |
Gemini 的流式输出需要特别注意。官方 streamGenerateContent 不加 alt=sse 时,返回的是 JSON 数组形式的分块。是否支持 alt=sse,需要查看你所用 ds2api 版本的说明。
2. 内部表示
请求进入适配层后,会先转换为统一结构,常见字段如下:
messages:统一的消息列表。role:统一为system、user、assistant、tool四类。content:内容块列表,文本、图片等都以块的形式存放。tool_calls:工具名称、参数和调用 ID。stream:是否流式返回。model:映射后的内部模型标识。
转换时要处理三处差异。第一,Claude 把 system 放在顶层字段,OpenAI 则放在消息列表里。第二,Gemini 用 model 表示助手角色,OpenAI 和 Claude 用 assistant。第三,Gemini 的消息内容放在 parts 中,而不是 content 字段。
3. 模型映射
客户端传入的模型名需要映射到后端模型。下面是示意配置:
| 客户端模型名 | 后端模型 | 说明 |
|---|---|---|
| gpt-4o | deepseek-chat | 示意 |
| claude-3-5-sonnet | deepseek-chat | 示意 |
| gemini-1.5-pro | deepseek-chat | 示意 |
客户端传入表中没有的模型名时,适配层返回的错误码和错误信息取决于 ds2api 的实现。遇到这类问题,先检查映射表,再检查请求中的模型名拼写。
4. 环境变量
密钥和地址放在环境变量中,不写进代码,也不提交到仓库:
export DS2API_BASE_URL="http://localhost:8000"export DS2API_KEY="你的ds2api密钥"
如果使用 .env 文件,请把它加入 .gitignore。
5. curl 验证
上线前,先用 curl 确认三条入口都能返回结果。这一步不依赖 SDK,可以快速判断问题出在网络、鉴权还是 SDK 配置。
# OpenAI 入口curl -sS "$DS2API_BASE_URL/v1/chat/completions" \-H "Authorization: Bearer $DS2API_KEY" \-H "Content-Type: application/json" \-d '{"model":"gpt-4o","messages":[{"role":"user","content":"ping"}]}'# Claude 入口,max_tokens 必填curl -sS "$DS2API_BASE_URL/v1/messages" \-H "x-api-key: $DS2API_KEY" \-H "anthropic-version: 2023-06-01" \-H "Content-Type: application/json" \-d '{"model":"claude-3-5-sonnet","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'# Gemini 入口curl -sS "$DS2API_BASE_URL/v1beta/models/gemini-1.5-pro:generateContent" \-H "x-goog-api-key: $DS2API_KEY" \-H "Content-Type: application/json" \-d '{"contents":[{"role":"user","parts":[{"text":"ping"}]}]}'
三条命令都应返回 HTTP 200 和对应协议格式的 JSON。如果某一条失败,先看第四节的排查表。
三、三种客户端的配置与流式代码
切换协议时,只改 base_url 不够。还需要同时调整 SDK 类、鉴权方式、模型名和响应解析代码。下面三个示例都使用环境变量读取配置。
依赖版本请以实际安装为准,建议在项目中固定版本号,并在测试环境跑通后再升级。
1. OpenAI SDK
OpenAI SDK 的 base_url 需要包含 /v1,因为 SDK 会直接拼接 /chat/completions。
import osfrom openai import OpenAIclient = OpenAI(base_url=f"{os.environ['DS2API_BASE_URL']}/v1", # 包含 /v1api_key=os.environ["DS2API_KEY"],)stream = client.chat.completions.create(model="gpt-4o",messages=[{"role": "user", "content": "用一句话解释协议适配层"}],stream=True,)for chunk in stream:if not chunk.choices:continuedelta = chunk.choices[0].deltaif delta.content: # 首尾块的 content 可能为空,需要判空print(delta.content, end="", flush=True)print()
OpenAI 的流式结束标志是 data: [DONE]。SDK 会处理这个标志,读者不需要手动判断。
2. Anthropic SDK
Anthropic SDK 的 base_url 不带 /v1,SDK 会自动拼接 /v1/messages。SDK 默认以 x-api-key 发送密钥,并自动带上 anthropic-version 请求头。
import osfrom anthropic import Anthropicclient = Anthropic(base_url=os.environ["DS2API_BASE_URL"], # 不带 /v1api_key=os.environ["DS2API_KEY"], # 以 x-api-key 发送)with client.messages.stream(model="claude-3-5-sonnet",max_tokens=512, # Claude 协议必填system="你是简洁的助手。",messages=[{"role": "user", "content": "用一句话解释协议适配层"}],) as stream:for text in stream.text_stream:print(text, end="", flush=True)print()
Claude 的流式输出是带事件名的 SSE。text_stream 已经把 content_block_delta 事件里的文本取出,因此不需要手动解析事件。如果你直接读取原始 SSE,需要分别处理 message_start、content_block_delta 和 message_stop。
3. Gemini(使用 httpx 直接调用)
Gemini 的 SDK 对 base_url 和鉴权方式的支持因版本而异。为了减少不确定因素,这里直接用 httpx 发送请求,鉴权头为 x-goog-api-key。
import jsonimport osimport httpxbase = os.environ["DS2API_BASE_URL"]key = os.environ["DS2API_KEY"]url = f"{base}/v1beta/models/gemini-1.5-pro:streamGenerateContent"body = {"contents": [{"role": "user", "parts": [{"text": "用一句话解释协议适配层"}]}]}with httpx.stream("POST",url,params={"alt": "sse"}, # 需确认 ds2api 是否支持该参数headers={"x-goog-api-key": key},json=body,timeout=60,) as r:r.raise_for_status()for line in r.iter_lines():if not line.startswith("data:"):continuechunk = json.loads(line[len("data:"):].strip())candidates = chunk.get("candidates", [])if not candidates:continuefor part in candidates[0].get("content", {}).get("parts", []):print(part.get("text", ""), end="", flush=True)print()
如果 ds2api 不支持 `alt=s

登录后可评论,请前往 登录 或 注册