OpenAI兼容上游(豆包)协议兼容性问题: namespace工具类型不支持 + Chat Completions桥接缺失input_image翻译
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 395
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
**提交人**: 一知山药
**客户端版本**: 0.1.20
---
## 现象
在 Cindy 中接入火山方舟豆包(Doubao-Seed-2.1-pro)作为自定义 OpenAI 兼容上游时,遇到两个协议兼容性问题,导致无法正常使用 Agent 工具调用和图片理解能力。
豆包已原生支持 OpenAI Responses API(官方文档提供了 `/api/v3/responses` 示例,含 `input_image`),但实现不完整。
### 问题1:Responses 原生模式下 `namespace` 工具类型导致请求被拒
测试连接成功(1455ms),但实际对话时报错:
```
unknown tool type: namespace
```
HTTP 400,错误码 `InvalidParameter`,参数位置 `tool.type`。
豆包的 Responses API 端点存在且基础功能可用,但不支持 `type: "namespace"` 工具类型。Cindy 在对话时发送包含 namespace 分组的工具定义,豆包解析器无法识别。
### 问题2:Chat Completions 桥接模式下 `input_image` 未翻译为 `image_url`
切换到 Chat Completions(Cindy 桥接)模式后,纯文本对话正常,但发送图片时报错:
```
Responses feature is not supported by the Chat Completions bridge: input content part 'input_image'
```
Responses API 中图片内容类型名是 `input_image`,而 Chat Completions API 中是 `image_url`(结构也不同)。桥接层在做格式转换时没有处理这个映射,直接报错。
---
## 复现步骤
1. 添加 Codex Runtime 上游:协议选「OpenAI Responses(原生)」,URL 填 `https://ark.cn-beijing.volces.com/api/v3`,模型 `doubao-seed-2-1-pro-260628`
2. 测试连接通过,但发送任意消息触发工具调用 → 报问题1
3. 切换到「Chat Completions(Cindy 桥接)」模式
4. 纯文本对话正常,但发送图片 → 报问题2
---
## 期望行为
1. **问题1**:在 Responses 原生模式下,检测到上游返回工具类型不支持的错误时自动降级——将 namespace 工具拍平为普通 `function` 类型后重试,或在配置中提供开关让用户选择不发送 namespace 工具。
2. **问题2**:桥接层增加 `input_image` → `image_url` 的格式翻译:
```json
// Responses 格式 (input_image)
{"type": "input_image", "image_url": "https://..."}
// 应翻译为 Chat Completions 格式 (image_url)
{"type": "image_url", "image_url": {"url": "https://..."}}
```
---
## 实际行为
两个模式均无法正常工作:Responses 模式下工具调用被拒(HTTP 400 unknown tool type: namespace),Chat Completions 桥接模式下图片消息直接报错不支持。
---
## 影响
豆包是国内主流大模型,这两个问题导致无法正常使用图片理解和 Agent 工具能力。其他 OpenAI 兼容但 Responses API 实现不完整的国产模型(如通义千问、文心一言等)也可能遇到类似问题。建议在桥接/适配层增加更健壮的降级和格式转换逻辑。
---
**OS**: win32 x64 (10.0.26200)
**界面语言**: zh-CN
Contributor guide
Research direction
Start at the OpenAI Responses native adapter and the Chat Completions bridge, then trace how namespace tools and input_image content parts are serialized. Reproduce both Doubao failures with the listed endpoints and add focused coverage showing that unsupported namespace tools are handled and input_image becomes a valid image_url part.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- ai, api
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100