火山方舟 Responses API 实战指南：从概念到「公司尽调 Dossier 生成器」

`Respenses API` 是什么？

Responses API 是火山方舟最新推出的 API 接口，原生支持高效的上下文管理，不仅延续了 Chat API 的易用性，还结合了更强的智能代理能力。随着大模型技术不断升级，Responses API 为开发各类面向实际行动的应用提供了更灵活的基础，并且支持函数调用等多种扩展能力，非常适合搭建智能助手、自动化工具等场景。

对比传统 `Chat API`

特性	传统 `Chat API`	`Responses API`
工具调用	需要手动实现完整流程	自动化内置支持
上下文管理	需自行维护会话状态	通过`previous_response_id`自动关联
代码复杂度	高（需处理多分支逻辑）	低（声明式配置）
内置工具	无，需要定制化集成	内置 `web_search`、`file_search` 工具
企业工具集成	需开发适配层	原生 `MCP` 协议支持

`Responses API` 功能

1）原生上下文管理机制

简化多轮对话开发流程；通过previous_response_id参数自动维护对话状态；无需手动管理会话历史和上下文窗口。

多轮调用 ：在多轮调用模式下，系统能够自动管理上下文，持续追踪和记忆之前的对话内容，使对话更加连贯自然，大大提升了智能交互体验。
重新生成对话：
- 通过灵活调用 previous_response_id 重新生成对话的树状分叉结构，并能在不同的分支中进行不同的操作；
- 在重新生成对话的场景中，系统能够根据不同的分支条件，灵活地执行多种的操作，从而实现更复杂的对话逻辑。
窗口截断 ：利用 delete 接口实现 Responses API 的窗口截断的功能，使得程序可以在 response 粒度上管理历史记忆，便于后续进行更复杂的对话。

2）更低成本的上下文缓存

前缀缓存
- 用户可以预先存储并缓存角色、背景等初始化信息， 后续调用模型时无需重复发送此信息给模型，即可自动命中初始化信息的缓存；
- 从而加快响应速度并降低使用成本，尤其适用于具有重复提示或标准化开头文本的应用。
Session 缓存 ：Responses API 支持自动储存历史上下文对话并保持缓存，通过调用 previous_response_id 在多轮对话等场景中命中缓存并实现更低的时延和推理成本。

3）高度简化的多工具集成能力

原生支持主流工具类型：
- web_search_preview：一键接入网络搜索；
- file_search：直接配置向量知识库（支持指定向量库ID和返回结果数量）；
- mcp：简单配置即可接入企业内部工具服务。
工具配置通过声明式 JSON 完成，无需复杂代码实现。

4）高度自动化的工具调用流程

无需手动实现工具调用逻辑（如函数调用解析、参数验证、结果串联）；
内置工具调用流程管理，自动处理多轮工具调用决策。

`Responses API` 优势

1）代码实现大幅简化

对比传统 Chat API，大幅节省代码量：

省去会话状态管理逻辑；
省去工具调用和结果处理逻辑。

2）开发效率显著提升

核心智能体实现仅需约 20 行代码；
工具扩展只需添加配置而非修改逻辑；
专注业务需求而非工程实现细节。

内置工具

工具列表	说明
联网搜索 `web search`	支持通过 `Responses API` 调用直接获取公开域互联网信息，适用于需动态获取最新网络数据的场景。工具通过模型自动判断是否需要搜索，并支持与自定义 `Function`、`MCP` 等工具混合使用
私域知识库搜索 `knowledge search`	支持通过 `Responses API` 调用直接获取企业私域知识库中的信息，适用于需基于企业专属数据解答问题的场景。工具通过模型自动判断是否需要调用私域知识库，支持与自定义 `Function`、`MCP` 等工具混合使用
图像处理 `image_process`	支持通过 `Responses API` 调用对输入图片执行画点、画线、旋转、缩放、框选/裁剪关键区域等基础操作。工具通过模型自动判断图像处理逻辑，支持与自定义 `Function` 混合使用，且可处理多轮视觉输入
云部署 / `Remote MCP Servers`	对接"`MCP MarketPlace`"，支持调用市场内各类垂直领域 `MCP` 工具；复杂任务（如多步数据查询+分析）支持多轮 `MCP` 调用；可与用户自定义 `Function`、`Web Search` 工具混合使用

快速上手：最小请求骨架

cURL（非流式）

bash 复制代码

curl --location "https://ark.cn-beijing.volces.com/api/v3/responses" \
--header "Authorization: Bearer $ARK_API_KEY" \
--header "Content-Type: application/json" \
--data '{
    "model": "doubao-seed-1-6-250615",
    "input": "你好呀。"
}'

实战：公司尽调 `Dossier` 生成器

目标与流程

输入：公司名/统一社会信用代码（USCC）输出：结构化 Dossier ------ 背景摘要、关键时间线 （成立、融资、处罚、重大交易...）、风险标签 （诉讼/负面/高管变更）、关键交易 （对手方/时间/金额/性质）、以及来源链接 。流程：web_search 拉权威来源 → 汇总时间线/风险/交易 → 按 JSON Schema 严格输出 → 可多轮追问（previous_response_id）。

web_search 在 Responses API 中通过 tools:[{ "type": "web_search" }] 启用。

代码片段

javascript 复制代码

async generateDossier(companyName, conversationHistory = []) {
    try {
      const settings = useSettingsStore()
      const config = settings.apiConfig
      
      const messages = [
        {
          role: 'system',
          content: `你是一个专业的公司尽调分析师。请根据提供的公司信息，生成一份详细的公司尽调Dossier，包含以下内容：
1. 公司背景信息
2. 重要时间线
3. 风险点分析（诉讼、负面新闻、高管变更等）
4. 关键交易信息
5. 信息来源链接

请以结构化的方式组织信息，使用清晰的标题和要点。`
        },
        ...conversationHistory,
        {
          role: 'user',
          content: `请为以下公司生成尽调Dossier：${companyName}`
        }
      ]
      
      const response = await axios.post(
        `${config.baseUrl}/responses`,
        {
          model: config.modelId,
          input: messages,
          tools: [{ type: 'web_search' }],
          stream: false
        },
        {
          headers: {
            'Authorization': `Bearer ${config.apiKey}`,
            'Content-Type': 'application/json'
          }
        }
      )
      console.log('API响应:', response.data);
      
      // 安全地解析响应数据
      let content = '';
      if (response.data.output && response.data.output.length > 0) {
        const lastOutput = response.data.output[response.data.output.length - 1];
        if (lastOutput.type === 'message' && lastOutput.content && lastOutput.content.length > 0) {
          content = lastOutput.content[0].text || '';
        }
      }
      
      console.log('解析的内容:', content);
      
      return {
        success: true,
        data: content,
        usage: response.data.usage
      }
    } catch (error) {
      console.error('API调用失败:', error)
      return {
        success: false,
        error: error.response?.data?.error?.message || error.message || 'API调用失败'
      }
    }
  }

`Prompt` 片段

diff 复制代码

系统指令：
- 你是公司尽调分析助手。只引用权威来源（监管公告/法院文书/证券交易所/主流媒体），每条结论附可点击链接。
- 先检索再生成；无法确认的信息留空或标注"未知"。
- 严格按给定 JSON Schema 输出；不得返回除 JSON 之外的内容。

用户输入（示例）：
公司：{公司名或统一社会信用代码}

最终效果图：

总结

为什么选 Responses API ：把会话接力、工具调用、结构化输出、SSE整合为统一协议，避免你在应用层反复造轮子；配合上下文缓存与（可选）上下文检索接口，工程化地兼顾控本、审计与可复盘。

如何快速落地 ：Dossier 这类企业实战非常契合 Responses 的范式：用 web_search 拉权威来源，严格按 JSON Schema 输出时间线/风险/关键交易与引用链接；多轮追问用 previous_response_id 增量改写；需要"边播边看"就开 SSE。

走向生产 ：把系统提示/术语表 放入前缀缓存、用模型别名/环境变量 做好灰度与回滚、对引用做可用性巡检 与去重归并 ，就能把PoC 提升到可维护、可审计、可扩展的生产形态。