豆包助手 API 是火山方舟平台提供的与豆包同源的企业级 API 服务，旨在帮助企业快速构建可落地、可规模化、可演进的 AI 应用。通过 Responses API，您可将豆包 App 同款 AI 能力（如日常沟通、深度沟通、联网搜索等）快速集成至自有应用，无需从零开发，即可获得安全、可靠且可控的优质 AI 体验。 ## 背景信息 ### 适用场景豆包助手 API 适用于从客户服务到业务决策的各类场景，主要有：日常知识问答、智能助手、智能硬件、学习教育、投研投顾等。 |**场景** |**一句话定位** |**核心价值点** |**典型场景** |**推荐方向** | |---|---|---|---|---| |日常沟通 |用于高频、情感丰富、即时反馈的人机交互场景。 |轻量、亲切、自然。 |* 生活助手：闲聊、陪伴、日常互动。|* 智能终端助手、儿童陪伴/陪读。|\ | | | |* 语音输出：讲解、导览、简单问答。|* 车载助手、手机助手。|\ | | | |* 指令式对话：帮我查、帮我写、帮我改。|* 文旅、展馆、商场、设备内置助手。 |\ | | | |* 轻量内容生成：润色、改写、翻译。 | | |深度沟通 |用于需要结构化思考、多步推理场景。 |思考纠偏、回复质量高、思考过程可理解。 |* 决策辅助：方案对比/策略分析/取舍权衡。|* 企业内部分析型助手（产品/运营/战略/管理支持）。|\ | | | |* 复杂创作：结构化回复/行业方案/商业分析（基于已有知识与逻辑）。|* 专业 Copilot（不联网也能给出高质量判断）。|\ | | | |* 学习与理解：原理解释/概念拆解/框架推演。 |* 学习型助手（进阶学习、体系化理解）。|\ | | | | |* 对“答案质量”要求高、但不要求实时性的场景。 | |联网搜索 |用于“答案依赖实时或外部信息”的问题。 |信息源丰富，实时获取，标注资料来源，兼顾信息时效性与可信度。 |* 核实信息与来源：用户快速确认事件或产品信息的真实性，并同时查看多方来源。|* 学术/研究型问题。|\ | | | |* 获取最新状态：用户实时获取政策、价格、行情等变化信息，确保决策基于当前数据。|* 高风险决策。|\ | | | |* 整合多渠道知识：用户将不同来源的信息汇总、分析，形成可直接使用的结论或摘要。|* 复杂系统分析。|\ | | | |* 验证对外输出内容：用户在讲解、报告或创作前，确保信息准确、来源可追溯。 |* 需要“不断修正假设”的问题探索。 | |边想边搜 |结合搜索与分析能力，对公开信息进行多轮检索与整合，用于研究型、学习型、分析型问题。 |推理过程外显，多轮自我校验、中间结论可见。 |* 车载助手，手机助手，语音助手。|* 研究型产品/分析工具。|\ | | | |* 售后客服，工单诊断，运营分析。|* 高风险、高不确定决策支持。|\ | | | |* 文旅场景、展览讲解，需要加入背景知识。|* 专业人员（研究、战略、投研）的探索式工作流。 |\ | | | |* 对信息准确性、可核验性要求高的场景。 | | ### **功能列表** 豆包助手 API 的上述适用场景分别对应一种功能，您可通过下表列出的功能标识在参数中指定使用哪项功能。 :::tip 单次仅可开启一个功能，不支持同时开启多个功能。 ::: |**功能名称** |**功能标识** |**功能介绍** | |---|---|---| |日常沟通 |chat |侧重自然对话，基于通用知识简要回答，无实时信息与深度分析。 | |深度沟通 |deep_chat |基于已有知识库深度解析，逻辑更严谨，但无实时数据支持。 | |联网搜索 |ai_search |通过实时联网获取最新资讯，信息时效性强，侧重结果呈现。 | |边想边搜 |reasoning_search |结合思考过程与实时搜索，先拆解问题再验证信息，逻辑链条完整。 | 为直观展示不同功能的差异，以下通过同一问题 “豆包 App 可以做什么？” 在不同功能模式下的响应效果对比： ```mixin-react return ( ); ``` 通过对比可见： * **日常沟通**适合闲聊交互，追求的是自然与效率。 * **深度沟通**适合复杂问题解析，追求的是正确性与思考质量。 * **联网搜索**适合获取实时资讯。 * **边想边搜**适合需要逻辑验证与深度洞察的场景。您可以根据实际业务需求选择对应功能模式，例如客服对话场景可选用**日常沟通**，行业研究场景可选用**边想边搜**。 ### **支持的模型** 参见[豆包助手](/docs/82379/1330310#a358e5b9)。 ### 计费信息参见[豆包助手计费](/docs/82379/1998171)。 ## 准备工作 1. 获取豆包助手 API 的测试参与资格。 :::tip 豆包助手 API 功能当前处于 beta 测试阶段，请联系销售人员或提交工单申请参与测试。 ::: 2. 开通豆包助手 API 服务。访问火山方舟管理控制台的[开通管理＞应用组件库＞豆包助手 API](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?&advancedActiveKey=component&tab=DoubaoAssistant)页面，并开通服务。 :::tip 如果您的控制台上没有该页面，可能是因为您尚未获得测试参与资格，或者您登录的账号不是已经获得资格的账号。 ::: ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/fa2f4dce1944448c9abe7d23fc5f41cd~tplv-goo7wpa0wc-image.image =650x) 3. 获取 API Key。详见[快速入门](/docs/82379/1399008)。 4. 将 API Key 配置到环境变量中。详见[环境变量配置指南](/docs/82379/1820161)。 5. 如需使用 SDK，请先安装或升级 SDK。详见[安装及升级 SDK](/docs/82379/1541595)。 ## **快速开始** ### **示例代码** ```mixin-react return ( headers = new HashMap<>(); headers.put("ark-beta-doubao-app", "true"); // 4. 构建工具配置 ToolDoubaoApp doubaoTool = ToolDoubaoApp.builder() .feature( DoubaoAppFeature.builder() .aiSearch( DoubaoAppFeatureItem.builder() .type("enabled") .roleDescription("你是科技领域助手，专业解答行业问题") .build() ) .build() ) .userLocation( UserLocation.builder() .type("approximate") .country("中国") .region("浙江") .city("杭州") .build() ) .build(); // 5. 构建请求参数 CreateResponsesRequest request = CreateResponsesRequest.builder() .model(MODEL_NAME) .stream(true) // 开启流式请求 .tools(Arrays.asList(doubaoTool)) .input(ResponsesInput.builder() .stringValue("今天有什么AI领域热点新闻") .build()) .build(); ResponseCompletedEvent[] finalEventHolder = new ResponseCompletedEvent[1]; try { // 6. 发送流式请求，遍历所有事件 Flowable streamResponse = service.streamResponse(request, headers); streamResponse.blockingForEach(event -> { System.out.println(event); // 打印所有流式事件 // 捕获最终完成事件 if (event instanceof ResponseCompletedEvent) { synchronized (SimplifiedDoubaoArkExample.class) { finalEventHolder[0] = (ResponseCompletedEvent) event; } } }); // 7. 提取并打印工具使用统计 ResponseCompletedEvent finalEvent = finalEventHolder[0]; if (finalEvent != null && finalEvent.getResponse() != null && finalEvent.getResponse().getUsage() != null) { System.out.println("\\n===== 工具使用统计 ====="); System.out.println("tool_usage: " + finalEvent.getResponse().getUsage().getToolUsage()); System.out.println("tool_usage_details: " + finalEvent.getResponse().getUsage().getToolUsageDetails()); } } catch (Exception e) { System.err.println("Create Response Error: " + e.getMessage()); return; } finally { // 关闭服务资源 service.shutdownExecutor(); } } } \`\`\` `}> ); ``` ### **参数说明** 详见[创建 Responses 模型请求](https://www.volcengine.com/docs/82379/1569618)。 ## **配置说明** ### **1. 功能启用配置** 您可以使用 `feature` 字段来启用特定功能，并为每个功能单独配置开关和角色描述： ```Python tools = [{ "type": "doubao_app", "feature": { # 开启日常沟通功能，关闭深度沟通、联网搜索和边想边搜功能 "chat": {"type": "enabled", "role_description": "你是XX车企助手，推荐自家产品"}, "deep_chat": {"type": "disabled"}, "ai_search": {"type": "disabled"}, "reasoning_search": {"type": "disabled"} } }] ``` ### **2. 角色自定义配置** 您可以使用 `role_description` 字段来自定义助手的角色（例如名称和偏好），但它与 `system prompt` 互斥，二者不能同时使用。 :::tip 如需使用自定义`system prompt`功能，请提交工单申请。 ::: ```Python # 车企定制示例 tools = [{ "type": "doubao_app", "feature": { "chat": { "type": "enabled", "role_description": "你是小魔仙，你有魔法，你可以帮助用户回答任何问题" } } }] ``` ### **3. 地理位置优化** 您可以通过设置 `user_location` 字段来优化与地理位置相关的搜索结果。请注意，该字段仅支持填写行政区划级别的信息。 ```Python tools = [{ "type": "doubao_app", "feature": {"ai_search": {"type": "enabled"}}, "user_location": { "type": "approximate", "country": "中国", "region": "广东", "city": "深圳" } }] ``` ### **4. 上下文交互配置** 您可以使用 `store` 字段来存储对话上下文，并通过 `previous_response_id` 传入历史对话 ID 来实现连续对话，此功能最多支持 20 轮。详情请参见[使用上下文缓存能力](/docs/82379/1585128#f61fe601)。 :::tip `store` 字段仅用于保存对话上下文，不会自动保留 `tools` 的配置。如果您希望在连续的对话中沿用相同的工具设置，就需要在每一轮请求中都为 `tools` 字段传入相同的值。 ::: ```Python response = client.responses.create( model="doubao-seed-1-6-251015", input=[{"role": "user", "content": "继续刚才的话题，还有其他热点吗"}], tools=tools, stream=True, store=True, # 存储当前对话上下文。此字段不存储tools，每次调用仍需给tools赋值。 previous_response_id="xxx" # 上一轮对话ID ) ``` ### **5. 用量查询** 可通过 Responses API 的`usage`字段查看工具使用情况。示例代码： ```Python # 提取工具使用统计 if final_event: tool_usage = final_event.response.usage.tool_usage tool_usage_details = final_event.response.usage.tool_usage_details print(f"工具总调用次数: {tool_usage}") print(f"各功能调用明细: {tool_usage_details}") ``` 示例返回值： ```Plain 工具总调用次数: ToolUsage(web_search=None, mcp=None, knowledge_search=None, doubao_app=1) 各功能调用明细: ToolUsageDetails(web_search=None, mcp=None, knowledge_search=None, doubao_app={'ai_search': 1}) ``` ## **实践案例** ### **企业角色定制示例** 以下示例展示如何为客户定制专属助手，实现品牌化交互体验： ```Bash curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \ --header "Authorization: Bearer $ARK_API_KEY" \ --header 'Content-Type: application/json' \ --header 'ark-beta-doubao-app: true' \ --data '{ "model": "doubao-seed-1-6-251015", "stream": true, "tools": [ { "type": "doubao_app", "feature": { "chat": { "type": "enabled", "role_description": "你是本企业专属助手，专业解答产品咨询、功能介绍、服务相关问题，优先推荐自家产品与服务，保持正面专业的沟通态度" } }, "user_location": { "type": "approximate", "country": "中国", "region": "省级行政区", "city": "地级市" } } ], "input": [ { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "介绍下你们的核心产品及优势" } ] } ] }' ``` ### **边想边搜功能示例** 以下示例展示边想边搜功能的使用，实时获取思考过程和搜索结果： ```Bash curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \ --header "Authorization: Bearer $ARK_API_KEY" \ --header 'Content-Type: application/json' \ --header 'ark-beta-doubao-app: true' \ --data '{ "model": "doubao-seed-1-6-251015", "stream": true, "tools": [ { "type": "doubao_app", "feature": { "reasoning_search": { "type": "enabled", "role_description": "你是专业资讯助手，通过搜索获取准确信息，详细说明思考过程" } } } ], "input": [ { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "2024年AI行业有哪些重大技术突破？" } ] } ] }' ``` ## **常见问题** ### **1. 功能可以混合使用吗？** 不可以。请注意，豆包助手 API 工具集不支持与[联网搜索 Web Search ](/docs/82379/1756990)、[私域知识库搜索 Knowledge Search](/docs/82379/1873396)、[云部署 MCP / Remote MCP](/docs/82379/1827534)、[图像处理 Image Process](/docs/82379/1798161) 等工具混合使用，也不支持与自定义函数[函数调用 Function Calling](/docs/82379/1262342)同时调用。 ### **2. 调用时有哪些常见的参数冲突？** 请注意以下参数的互斥或限制： * `role_description` 与 `system prompt` 参数互斥。如果您同时指定这两个参数，请求将返回 `400` 错误。 * `max_tool_call` 参数当前无效。如果您在请求中使用该参数，将会返回冲突错误。 * `caching` 参数当前无效。如果您在请求中使用该参数，将会返回 `400` 错误。 ### **3. API 的调用频率有限制吗？** 是的，API 的调用频率有限制。默认情况下，单个账号调用频率上限为 2 QPS（每秒查询次数）。如果当前配额无法满足您的需求，请提交工单申请扩容。 ### **4. 调用时提示“功能未授权”怎么办？** 如果您尚未开通豆包助手 API 的使用权限，调用 API 时就会收到此错误。请您先前往火山方舟管理控制台开通豆包助手 API。 ### **5. 豆包 API 和豆包 App 有什么区别？** 主要区别在于目标用户和使用方式： * **豆包 API**：专为企业开发者设计，通过火山方舟平台提供。您可以使用它将豆包的 AI 功能集成到自己的应用程序中。 * **豆包 App**：一款面向个人用户的独立应用程序，供用户直接使用。 ### **6. 使用豆包 API 有哪些限制？** 与豆包 App 相比，API 的主要限制如下： * **输入限制**：目前仅支持文本输入，不支持图片或视频。同时，您也无法调整 `top_p`、`temperature`、`max_tokens` 等模型参数。 * **功能与工具限制**：每次 API 调用只能启用一个豆包助手 API 功能（如 `ai_search`）。您无法自定义工具的内部参数（如内容源、搜索轮次），也不能将其与其他自定义函数、内置工具或 MCP 混合使用。 ### **7. 使用豆包 API 是否需要付费？** 是的，使用豆包 API 需要付费。我们目前采用按次调用的计费模式，不收取 Token 费用。具体价格请参考[豆包助手计费](/docs/82379/1998171)。 ### **8. 使用了豆包 API，是否意味着我的应用是和豆包“联合出品”的？** 不是。使用豆包 API 仅表示您的应用集成了豆包的 AI 能力，**不代表**您的产品是与豆包 App “联合出品”或“官方合作”的产品。您需要明确说明技术来源，避免引起用户混淆。 ### **9. 我应该如何宣传产品中集成的豆包 API 功能？** 在对外宣传时，您应使用清晰准确的表述，例如： * “本产品由豆包助手 API 提供技术支持”。 * “本功能基于豆包助手 API 实现”。请明确说明您是通过 API 接入，并避免使用“与豆包联合出品”、“官方合作”等可能引起误解的词语。