logo

ds2api 如何用一套接口兼容三大协议

作者:carzy2026.11.17 03:18浏览量:0

简介:这篇文章拆解 ds2api 的协议适配层,说明多协议入口、统一内部表示和响应回写的协作方式。文中给出 OpenAI、Claude、Gemini 三套客户端的配置与流式代码,附 curl 验证命令、常见报错排查表和上线前的稳定性与合规检查清单,读者可以按步骤接入并快速定位问题。

先说明一点:文中路径、变量名和映射表都是示意。你实际部署的 ds2api 版本可能有不同的字段和路径,上线前以它的文档和实际响应为准。

一、设计架构

ds2api 位于客户端和模型之间,是一个协议适配层。它的请求链路可以拆成五步:

  1. 客户端按自己熟悉的协议发起请求,例如 OpenAI SDK 调用 /v1/chat/completions。
  2. 协议入口根据路由选择对应的解析逻辑,把请求体转换为内部结构。
  3. 适配层查找模型映射表,把客户端传入的模型名转到后端模型。
  4. 后端调用完成,返回的文本、工具调用和用量信息被统一保存。
  5. 适配层按入口协议重新组装响应,写回客户端。

这样设计的好处是,转换逻辑集中在一处。接入的客户端越多,需要维护的转换规则只增长一份,不会按”客户端乘以协议”的组合数增长。

二、三套入口与内部表示

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. 环境变量

密钥和地址放在环境变量中,不写进代码,也不提交到仓库:

  1. export DS2API_BASE_URL="http://localhost:8000"
  2. export DS2API_KEY="你的ds2api密钥"

如果使用 .env 文件,请把它加入 .gitignore。

5. curl 验证

上线前,先用 curl 确认三条入口都能返回结果。这一步不依赖 SDK,可以快速判断问题出在网络、鉴权还是 SDK 配置。

  1. # OpenAI 入口
  2. curl -sS "$DS2API_BASE_URL/v1/chat/completions" \
  3. -H "Authorization: Bearer $DS2API_KEY" \
  4. -H "Content-Type: application/json" \
  5. -d '{"model":"gpt-4o","messages":[{"role":"user","content":"ping"}]}'
  6. # Claude 入口,max_tokens 必填
  7. curl -sS "$DS2API_BASE_URL/v1/messages" \
  8. -H "x-api-key: $DS2API_KEY" \
  9. -H "anthropic-version: 2023-06-01" \
  10. -H "Content-Type: application/json" \
  11. -d '{"model":"claude-3-5-sonnet","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'
  12. # Gemini 入口
  13. curl -sS "$DS2API_BASE_URL/v1beta/models/gemini-1.5-pro:generateContent" \
  14. -H "x-goog-api-key: $DS2API_KEY" \
  15. -H "Content-Type: application/json" \
  16. -d '{"contents":[{"role":"user","parts":[{"text":"ping"}]}]}'

三条命令都应返回 HTTP 200 和对应协议格式的 JSON。如果某一条失败,先看第四节的排查表。

三、三种客户端的配置与流式代码

切换协议时,只改 base_url 不够。还需要同时调整 SDK 类、鉴权方式、模型名和响应解析代码。下面三个示例都使用环境变量读取配置。

依赖版本请以实际安装为准,建议在项目中固定版本号,并在测试环境跑通后再升级。

1. OpenAI SDK

OpenAI SDK 的 base_url 需要包含 /v1,因为 SDK 会直接拼接 /chat/completions。

  1. import os
  2. from openai import OpenAI
  3. client = OpenAI(
  4. base_url=f"{os.environ['DS2API_BASE_URL']}/v1", # 包含 /v1
  5. api_key=os.environ["DS2API_KEY"],
  6. )
  7. stream = client.chat.completions.create(
  8. model="gpt-4o",
  9. messages=[{"role": "user", "content": "用一句话解释协议适配层"}],
  10. stream=True,
  11. )
  12. for chunk in stream:
  13. if not chunk.choices:
  14. continue
  15. delta = chunk.choices[0].delta
  16. if delta.content: # 首尾块的 content 可能为空,需要判空
  17. print(delta.content, end="", flush=True)
  18. print()

OpenAI 的流式结束标志是 data: [DONE]。SDK 会处理这个标志,读者不需要手动判断。

2. Anthropic SDK

Anthropic SDK 的 base_url 不带 /v1,SDK 会自动拼接 /v1/messages。SDK 默认以 x-api-key 发送密钥,并自动带上 anthropic-version 请求头。

  1. import os
  2. from anthropic import Anthropic
  3. client = Anthropic(
  4. base_url=os.environ["DS2API_BASE_URL"], # 不带 /v1
  5. api_key=os.environ["DS2API_KEY"], # 以 x-api-key 发送
  6. )
  7. with client.messages.stream(
  8. model="claude-3-5-sonnet",
  9. max_tokens=512, # Claude 协议必填
  10. system="你是简洁的助手。",
  11. messages=[{"role": "user", "content": "用一句话解释协议适配层"}],
  12. ) as stream:
  13. for text in stream.text_stream:
  14. print(text, end="", flush=True)
  15. 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。

  1. import json
  2. import os
  3. import httpx
  4. base = os.environ["DS2API_BASE_URL"]
  5. key = os.environ["DS2API_KEY"]
  6. url = f"{base}/v1beta/models/gemini-1.5-pro:streamGenerateContent"
  7. body = {
  8. "contents": [
  9. {"role": "user", "parts": [{"text": "用一句话解释协议适配层"}]}
  10. ]
  11. }
  12. with httpx.stream(
  13. "POST",
  14. url,
  15. params={"alt": "sse"}, # 需确认 ds2api 是否支持该参数
  16. headers={"x-goog-api-key": key},
  17. json=body,
  18. timeout=60,
  19. ) as r:
  20. r.raise_for_status()
  21. for line in r.iter_lines():
  22. if not line.startswith("data:"):
  23. continue
  24. chunk = json.loads(line[len("data:"):].strip())
  25. candidates = chunk.get("candidates", [])
  26. if not candidates:
  27. continue
  28. for part in candidates[0].get("content", {}).get("parts", []):
  29. print(part.get("text", ""), end="", flush=True)
  30. print()

如果 ds2api 不支持 `alt=s

发表评论

活动