Skip to content

增强 ResponsesApiConverter 对 Web Search 工具及 Grounding Metadata 的支持 #660

@muverystrong

Description

@muverystrong

背景

Responses API 转换层(ResponsesApiConverter)在处理 Chat Completion ↔ Responses API 互转时,存在三处功能缺失,导致 Doubao 等支持 Web Search 和引用标注(grounding)的模型无法正常工作:

  1. 工具列表转换逻辑假定所有工具均包含 function 字段,当使用 web_search 等非函数类工具时,代码对 nullfunction 直接访问导致 NPE,且工具的 extra_body(如 max_tool_calls)不会被传递。
  2. token 用量转换时,tool_usage(记录各工具调用次数,如 Web Search 调用次数)未被保留,导致上游调用方无法获取工具用量统计。
  3. 响应转换时,content item 中的 annotations(URL 引用、文档引用等)未被提取并映射到 Chat Completion 的 grounding_metadata,导致引用信息丢失。

诉求

  1. 非函数类工具支持convertToolsToResponsesApi 方法对 function == null 的工具,仅设置 type 字段并透传 extra_body,不再访问 nullfunction
  2. tool_usage 透传convertToken 方法将 ResponsesApiResponse.Usage#tool_usage 映射到 CompletionResponse.TokenUsage#tool_usage
  3. annotations → grounding_metadataconvertResponsesToChatCompletion 方法汇总所有 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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions