火山引擎方舟API工具扩展指南

火山引擎方舟API工具扩展指南

在火山引擎方舟（Volcengine Ark）的 API 中，tools数组除了内置的web_search，还支持内置垂直工具和**自定义函数（Function Calling）**两大扩展方向。以下是具体功能、配置示例及核心价值说明：

一、内置垂直工具（官方封装，开箱即用）

方舟 Responses API 提供了多个预封装的内置工具，无需自行开发逻辑，直接配置即可调用。

1. 图像处理工具（image_processing）

用途：对输入图片进行分析、编辑或理解（如 OCR 文字识别、物体检测、图像风格描述等）。
配置示例：

data={"model":"doubao-1.5-vision-pro-32k","input":[{"role":"user","content":[{"type":"input_text","text":"识别这张图片里的所有文字"},{"type":"input_image","image_url":"https://example.com/receipt.jpg"}]}],"tools":[{"type":"image_processing","task":"ocr"# 可选：object_detection（物体检测）、image_caption（图像描述）}]}

2. 私域知识库搜索（knowledge_base_search）

用途：对接你在火山方舟上传的私有知识库（如企业文档、产品手册、内部FAQ），让模型基于你的专属数据回答问题。
配置示例：

data={"model":"doubao-seed-2-0-pro-260215","input":[{"role":"user","content":"我们公司2025年的年假制度是什么？"}],"tools":[{"type":"knowledge_base_search","knowledge_base_id":"kb-1234567890",# 替换为你的知识库ID"top_k":3# 召回最相关的3条文档片段}]}

3. MCP 工具市场（mcp_marketplace）

用途：直接调用火山方舟 MCP 市场的垂直工具（如巨量千川数据分析、飞书文档操作、企业ERP查询等），无需自行对接第三方API。
配置示例：

data={"model":"doubao-seed-2-0-pro-260215","input":[{"role":"user","content":"帮我查一下我巨量千川账户昨天的消耗和ROI"}],"tools":[{"type":"mcp_marketplace","mcp_tool_id":"mcp-qianchuan-stats",# 替换为市场中的工具ID"auth_token":"your-mcp-auth-token"# 工具授权凭证}]}

二、自定义函数（Function Calling）

你可以通过type: "function"定义任意业务逻辑的工具，模型会自动判断何时调用你的函数，并将结果整合到回答中。

核心流程

1. 在tools中定义函数的名称、描述和参数 schema；
2. 模型判断需要调用时，返回tool_calls字段（包含函数名和参数）；
3. 你的代码执行函数逻辑，将结果通过tool_message传回给模型；
4. 模型基于函数结果生成最终回答。

经典示例 1：天气查询

importosimportrequestsfromvolcenginesdkarkruntimeimportArk# 1. 定义工具函数（实际业务逻辑）defget_current_weather(location,unit="摄氏度"):"""模拟调用天气API，返回指定地点的天气"""# 这里替换为真实的天气API调用（如和风天气、OpenWeatherMap）weather_data={"北京":{"temp":25,"condition":"晴朗"},"上海":{"temp":22,"condition":"多云"}}city_weather=weather_data.get(location,{"temp":"未知","condition":"未知"})returnf"{location}今天{city_weather['condition']}，温度{city_weather['temp']}{unit}。"# 2. 配置 API 请求（包含函数定义）client=Ark(api_key=os.environ.get("ARK_API_KEY"))response=client.responses.create(model="doubao-seed-2-0-pro-260215",input=[{"role":"user","content":"北京今天天气怎么样？"}],tools=[{"type":"function",","function":{"name":"get_current_weather","description":"获取指定城市的当前天气信息","parameters":{"type":"object","properties":{"location":{"type":"string","description":"城市名称，如北京、上海"},"unit":{"type":"string","enum":["摄氏度","华氏度"],"description":"温度单位，默认摄氏度"}},"required":["location"]}}}])# 3. 处理模型的工具调用请求ifresponse.output[0].type=="tool_calls":tool_call=response.output[0].tool_calls[0]# 执行你的函数function_result=get_current_weather(**tool_call.function.arguments)# 4. 将结果传回模型，获取最终回答final_response=client.responses.create(model="doubao-seed-2-0-pro-260215",input=[{"role":"user","content":"北京今天天气怎么样？"},response.output[0],# 模型的 tool_calls 消息{"role":"tool","tool_call_id":tool_call.id,"content":[{"type":"tool_output","output":function_result}]}])print(final_response.output[0].content[0].text)

经典示例 2：数据库查询

tools=[{"type":"function",","function":{"name":"query_user_order","description":"根据用户ID查询其最近的订单信息","parameters":{"type":"object","properties":{"user_id":{"type":"string","description":"用户的唯一ID"},"limit":{"type":"integer","description":"返回订单数量，默认5条","default":5}},"required":["user_id"]}}}]

三、组合使用示例（内置工具 + 自定义函数）

你可以同时配置多个工具，让模型自主判断调用哪个：

data={"model":"doubao-seed-2-0-pro-260215","input":[{"role":"user","content":"帮我分析一下这张订单截图，然后查一下我们公司的退款政策"}],"tools":[{"type":"web_search","max_keyword":2},# 联网搜索通用信息{"type":"image_processing","task":"ocr"},# 识别图片文字{"type":"knowledge_base_search","knowledge_base_id":"kb-company-policies"# 查内部知识库},{"type":"function",","function":{"name":"query_order_status","description":"根据订单号查询物流状态","parameters":{"type":"object","properties":{"order_id":{"type":"string"}},"required":["order_id"]}}}]}