火山引擎方舟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：天气查询

import os
import requests
from volcenginesdkarkruntime import Ark

# 1. 定义工具函数（实际业务逻辑）
def get_current_weather(location, unit="摄氏度"):
    """模拟调用天气API，返回指定地点的天气"""
    # 这里替换为真实的天气API调用（如和风天气、OpenWeatherMap）
    weather_data = {
        "北京": {"temp": 25, "condition": "晴朗"},
        "上海": {"temp": 22, "condition": "多云"}
    }
    city_weather = weather_data.get(location, {"temp": "未知", "condition": "未知"})
    return f"{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. 处理模型的工具调用请求
if response.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"]}
            }
        }
    ]
}