背景
Responses API 转换层(ResponsesApiConverter)在处理 Chat Completion ↔ Responses API 互转时,存在三处功能缺失,导致 Doubao 等支持 Web Search 和引用标注(grounding)的模型无法正常工作:
- 工具列表转换逻辑假定所有工具均包含
function 字段,当使用 web_search 等非函数类工具时,代码对 null 的 function 直接访问导致 NPE,且工具的 extra_body(如 max_tool_calls)不会被传递。
- token 用量转换时,
tool_usage(记录各工具调用次数,如 Web Search 调用次数)未被保留,导致上游调用方无法获取工具用量统计。
- 响应转换时,content item 中的
annotations(URL 引用、文档引用等)未被提取并映射到 Chat Completion 的 grounding_metadata,导致引用信息丢失。
诉求
- 非函数类工具支持:
convertToolsToResponsesApi 方法对 function == null 的工具,仅设置 type 字段并透传 extra_body,不再访问 null 的 function。
- tool_usage 透传:
convertToken 方法将 ResponsesApiResponse.Usage#tool_usage 映射到 CompletionResponse.TokenUsage#tool_usage。
- annotations → grounding_metadata:
convertResponsesToChatCompletion 方法汇总所有 content item 的 annotations,在 Choice 上以 grounding_metadata.annotations 形式透出。
预期影响
- 使用
web_search 工具的 Doubao 等模型可正常通过 Responses API 路径调用,不再 NPE。
- 调用方可获取
tool_usage 统计(如 Web Search 调用次数),便于计费与监控。
- Chat Completion 响应中可获取
grounding_metadata.annotations,支持前端展示引用来源。
证据
新增单元测试 ResponsesApiConverterTest,覆盖以下三个场景:
convertChatCompletionToResponses_shouldPreserveWebSearchTool
convertToken_shouldPreserveToolUsage
convertResponsesToChatCompletion_shouldPreserveAnnotationsAsGroundingMetadata
相关链接
- 修改文件:
api/server/src/main/java/com/ke/bella/openapi/protocol/completion/ResponsesApiConverter.java
- 测试文件:
api/server/src/test/java/com/ke/bella/openapi/protocol/completion/ResponsesApiConverterTest.java
背景
Responses API 转换层(
ResponsesApiConverter)在处理 Chat Completion ↔ Responses API 互转时,存在三处功能缺失,导致 Doubao 等支持 Web Search 和引用标注(grounding)的模型无法正常工作:function字段,当使用web_search等非函数类工具时,代码对null的function直接访问导致 NPE,且工具的extra_body(如max_tool_calls)不会被传递。tool_usage(记录各工具调用次数,如 Web Search 调用次数)未被保留,导致上游调用方无法获取工具用量统计。annotations(URL 引用、文档引用等)未被提取并映射到 Chat Completion 的grounding_metadata,导致引用信息丢失。诉求
convertToolsToResponsesApi方法对function == null的工具,仅设置type字段并透传extra_body,不再访问null的function。convertToken方法将ResponsesApiResponse.Usage#tool_usage映射到CompletionResponse.TokenUsage#tool_usage。convertResponsesToChatCompletion方法汇总所有 content item 的annotations,在Choice上以grounding_metadata.annotations形式透出。预期影响
web_search工具的 Doubao 等模型可正常通过 Responses API 路径调用,不再 NPE。tool_usage统计(如 Web Search 调用次数),便于计费与监控。grounding_metadata.annotations,支持前端展示引用来源。证据
新增单元测试
ResponsesApiConverterTest,覆盖以下三个场景:convertChatCompletionToResponses_shouldPreserveWebSearchToolconvertToken_shouldPreserveToolUsageconvertResponsesToChatCompletion_shouldPreserveAnnotationsAsGroundingMetadata相关链接
api/server/src/main/java/com/ke/bella/openapi/protocol/completion/ResponsesApiConverter.javaapi/server/src/test/java/com/ke/bella/openapi/protocol/completion/ResponsesApiConverterTest.java