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

火山引擎方舟API工具扩展指南目录火山引擎方舟API工具扩展指南一、内置垂直工具官方封装开箱即用1. 图像处理工具image_processing2. 私域知识库搜索knowledge_base_search3. MCP 工具市场mcp_marketplace二、自定义函数Function Calling核心流程经典示例 1天气查询经典示例 2数据库查询三、组合使用示例内置工具 自定义函数在火山引擎方舟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,# 替换为你的知识库IDtop_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,# 替换为市场中的工具IDauth_token:your-mcp-auth-token# 工具授权凭证}]}二、自定义函数Function Calling你可以通过type: function定义任意业务逻辑的工具模型会自动判断何时调用你的函数并将结果整合到回答中。核心流程在tools中定义函数的名称、描述和参数 schema模型判断需要调用时返回tool_calls字段包含函数名和参数你的代码执行函数逻辑将结果通过tool_message传回给模型模型基于函数结果生成最终回答。经典示例 1天气查询importosimportrequestsfromvolcenginesdkarkruntimeimportArk# 1. 定义工具函数实际业务逻辑defget_current_weather(location,unit摄氏度):模拟调用天气API返回指定地点的天气# 这里替换为真实的天气API调用如和风天气、OpenWeatherMapweather_data{北京:{temp:25,condition:晴朗},上海:{temp:22,condition:多云}}city_weatherweather_data.get(location,{temp:未知,condition:未知})returnf{location}今天{city_weather[condition]}温度{city_weather[temp]}{unit}。# 2. 配置 API 请求包含函数定义clientArk(api_keyos.environ.get(ARK_API_KEY))responseclient.responses.create(modeldoubao-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].typetool_calls:tool_callresponse.output[0].tool_calls[0]# 执行你的函数function_resultget_current_weather(**tool_call.function.arguments)# 4. 将结果传回模型获取最终回答final_responseclient.responses.create(modeldoubao-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]}}}]}