← 返回博客

AI Agent 工具调用怎么计费?搜索、文件检索与存储账单拆解

拆解 AI Agent 在模型 Token 之外的独立账单结构:对比 OpenAI、Claude 与 Gemini 官方托管搜索、文件检索与存储计费口径,结合 Python Decimal 敏感性算例与自建检索分层架构,厘清业务迁移与真实部署成本边界。

评估 AI Agent 运行成本时,仅关注模型输入与输出 Token 价格容易产生预算偏差。在实际架构中,一旦 Agent 启用官方托管搜索、挂载私有文件或持久化向量索引,模型厂商会引入独立的计费维度:工具调用费(Calls)、检索查询费(Queries)以及每日向量存储费(GiB-day)。

本文基于 2026 年 11 月 14 日核准的厂商官方文档,拆解工具调用与存储的计费口径,结合离线 Decimal 敏感性算例分析多维账单结构,并说明自建检索与 APIBox 文本推理分层的工程核验边界。

1. 解构 Agent 账单:四维计费单元与层级穿透

Agent 运行生命周期通常跨越四个层级,各层级计量逻辑相互独立:

  1. 终端用户任务(User Task):用户触发的完整业务流程(例如生成一份行业竞品综述)。一个任务往往包含多轮规划与多次工具调用。
  2. 模型推理请求(API Request):向网关发起的单次 HTTP 请求,产生常规 prompt tokens、completion tokens 及思考推理 tokens。
  3. 托管工具调用与查询(Tool Calls / Queries):模型在规划执行阶段调用的外部托管能力。各厂商对“调用次数(Call)”与“派生查询数(Query)”的计量标准不同。
  4. 持久化索引存储(GB-day Storage):文档切片与向量数据驻留于厂商云端所占用的物理存储体积,通常按日累计,与当日调用次数无关。

需要厘清的是计费边界:工具执行费与模型处理费属于不同维度的计量,而非同一 Token 重复扣费。搜索或文件检索召回的内容作为上下文回填至模型输入,按照常规输入 Token 计费,已包含在总输入账单中;生成的思考 Token 计入输出账单,同样不在此之外叠加。缓存与模型特例则按对应厂商规则处理。

2. 主流厂商官方托管工具计费机制横向对比

根据 2026 年 11 月 14 日核准的公开文档,OpenAI、Anthropic 与 Google 在搜索与检索计量规则上存在明确差异。

OpenAI:明确的调用费与每日 GiB 累加

参考 OpenAI 官方 Pricing 与 OpenAI 检索指南:

  • Web Search:标准(非 preview)Web search 工具调用费为 $10 / 1,000 calls(每次调用 $0.010)。搜索返回的内容按对应模型的输入规则计费;模型特例见官方价格表。
  • File Search:在 Responses API 体系下,文件检索调用费为 $2.50 / 1,000 calls(每次调用 $0.0025)。
  • 向量存储:费率为 $0.10 / GiB / 天。计费体积指所有 vector stores 解析切片(chunks)加向量数据(embeddings)的总体积,而非原始文件上传体积。
  • 免费抵扣与清理:官方按所有 vector stores 的合计体积计算首 1 GiB 免费额度,不能为每个 store 重复抵扣。expires_after 可作为 OpenAI vector_store 的生命周期配置示例;到期删除关联的 vector_store.file 对象并停止对应存储计费,不应据此认定原始上传文件也已删除。

Anthropic Claude:按搜索动作计量

参考 Anthropic Web Search 指南:

  • 搜索费用:Web search 费率为 $10 / 1,000 searches(每次搜索动作 $0.010),外加标准 Token 费用。调用计费以接口响应中的 usage.server_tool_use.web_search_requests 为核算依据。
  • 动作粒度与失败处理:搜索费按执行的 search 动作计量,不是每 HTTP 请求固定一次,且与返回结果条数无关。若某次搜索执行失败,不收取该次搜索工具费,但该次 API 请求的 Token 仍正常计费。
  • 单轮限制:max_uses 用于限制当前单个 turn 内模型触发搜索的最大次数。一个 turn 可跨 pause_turn 续接请求,不等于单次 HTTP 请求;失败的搜索同样会消耗 max_uses。本文只讨论基础 Messages 搜索配置,其他产品限制以对应文档为准。

Google Gemini:项目级多查询计量与免费存储

参考 Google Grounding 文档 与 Google File Search 文档:

  • Gemini 3 搜索计量:针对 Gemini 3 及更新模型,Google Grounding 官方明确以搜索查询(query)计费。每个项目每月在所有 Gemini 3 及更新模型间共享 5,000 次免费搜索查询,超出后按 $14 / 1,000 queries 计费,不可按模型单独重置。空查询在统计计费 unique queries 时忽略。
  • File Search 特例:Google File Search 仅在导入索引时收取一次性 Embeddings 费用;向量存储与查询阶段的 Embeddings 均免费,属于没有独立检索查询费的特例;检索召回并注入上下文的文本按常规 context tokens 计费。
厂商 / 平台托管搜索计费口径文件检索调用费 (Calls)向量存储费 (Storage)检索回填 Context Tokens
OpenAI$10 / 1,000 calls (标准非 preview)$2.50 / 1,000 calls (Responses API)$0.10 / GiB / 天 (所有 Store 合计共享首 1 GiB 免费)按对应模型输入规则计费 (模型特例见官方价格表)
Anthropic$10 / 1,000 searches (按 search 动作计)本文未评估独立文件检索/存储产品本文未评估独立文件检索/存储产品按对应模型输入规则计费
Google项目月享 5,000 免费 queries (Gemini 3+ 共享);超额 $14 / 1,000查询阶段无额外调用费 (特例)存储免费 (仅导入收一次性 Embeddings 费)按对应模型输入规则计费

官方事实依据请参考上述公开链接。

3. 假设算例与敏感性分析:成本结构推演

说明:以下测算为纯理论假设工程预算,非实测基准、非客户账单,亦非 APIBox 平台的工具服务报价。

设定一个月度承接 10,000 个提交任务 的知识检索场景,基于 OpenAI 标准公开费率推演:

  • Web Search 调用量:平均每个任务执行 2 次联网搜索,月度共计 20,000 次 calls,费用为 20,000 * ($10 / 1,000) = $200.00。
  • File Search 调用量:平均每个任务执行 1 次文件检索,月度共计 10,000 次 calls,费用为 10,000 * ($2.50 / 1,000) = $25.00。
  • 向量存储:计费范围内所有 vector stores 合计占用稳定在 6 GiB。扣除每日共享的 1 GiB 免费额度后,按 30 天计费:(6 - 1) GiB * 30 天 * $0.10/GiB/天 = $15.00。daily_total_gib 必须汇总同一免费额度覆盖的所有 stores,不能按项目或 store 重复减免;动态存储按日度代表值近似,日内变动时需核对供应商计量口径,不等同官方最终账单。
  • 非 Token 费用小计:$200.00 + $25.00 + $15.00 = $240.00。分摊到每个提交任务的非 Token 基础设施支出约为 $0.024。
  • 模型 Token 费用:假设所有任务消耗的模型 Token(含上下文、回填文本及输出)合计为 $100.00。

在官方基线费率下,该算例的总预算为:

总预算 = $240.00 (非 Token 工具与存储) + $100.00 (模型 Token) = $340.00

敏感性假设分析

假设仅模型 Token 支出降低 90%(由 $100.00 降至 $10.00),而外部托管搜索与存储费用维持 $240.00 不变(注意:工具费用是独立计量项,此处仅在敏感性假设中保持恒定,非真实固定成本):

  • 新预算总计:$240.00 + $10.00 = $250.00。
  • 总支出降幅:($340.00 - $250.00) / $340.00 = 26.47%。
预算构成项官方标准假设成本Token 降至 $10 场景 (工具不变)占初始总预算比例
Web Search (20,000 calls)$200.00$200.0058.82%
File Search (10,000 calls)$25.00$25.007.35%
Vector Storage (6 GiB, 30天)$15.00$15.004.41%
非 Token 开销小计$240.00$240.0070.59%
模型 Token 支出 (含回填)$100.00$10.0029.41%
全月综合总预算$340.00$250.00本算例降幅 26.47%

需要强调,26.47% 仅为本特定假设算例的数学推导结果,不能推广为所有 Agent 架构的通用降幅。这表明在检索密集型架构中,如果工具调用与存储开支未同步优化,单独降低 Token 价格对整体预算的拉动作用存在边际效应。

4. Python Decimal 预算精算脚本

以下脚本基于 Python 标准库 decimal 实现,提供高精度离线推演,不发起网络请求,费率基准为 2026 年 11 月 14 日官方公开数据。

"""
OpenAI Hosted Tools 离线预算推演函数
核验参考日期: 2026-11-14 (官方公开费率)
"""
from decimal import Decimal, ROUND_HALF_UP

WEB_SEARCH_PRICE_PER_CALL = Decimal("0.010")    # $10 / 1,000 calls
FILE_SEARCH_PRICE_PER_CALL = Decimal("0.0025")   # $2.50 / 1,000 calls
STORAGE_PRICE_PER_GIB_DAY = Decimal("0.10")     # $0.10 / GiB-day
FREE_TIER_GIB_PER_DAY = Decimal("1.0")          # 每天所有计费 stores 合计共享 1 GiB 免费

def estimate(model_usd, web_calls, file_calls, daily_total_gib):
    """
    计算给定周期内的 Agent 综合预算明细。
    """
    if model_usd is None:
        raise ValueError("model_usd 不能为空")
    try:
        token_cost = Decimal(str(model_usd))
    except Exception as exc:
        raise ValueError(f"无效的 model_usd 数值: {model_usd}") from exc
    if not token_cost.is_finite() or token_cost < Decimal("0"):
        raise ValueError("model_usd 必须为非负有限数值")

    if type(web_calls) is not int or web_calls < 0:
        raise ValueError("web_calls 必须为非负整数")
    if type(file_calls) is not int or file_calls < 0:
        raise ValueError("file_calls 必须为非负整数")

    if not isinstance(daily_total_gib, (list, tuple)):
        raise ValueError("daily_total_gib 必须为 list 或 tuple")

    web_cost = Decimal(web_calls) * WEB_SEARCH_PRICE_PER_CALL
    file_cost = Decimal(file_calls) * FILE_SEARCH_PRICE_PER_CALL

    storage_cost = Decimal("0")
    for day_idx, gib_entry in enumerate(daily_total_gib):
        if gib_entry is None:
            raise ValueError(f"第 {day_idx + 1} 天存储用量不能为 None")
        try:
            day_gib = Decimal(str(gib_entry))
        except Exception as exc:
            raise ValueError(f"第 {day_idx + 1} 天存储用量无效: {gib_entry}") from exc
        if not day_gib.is_finite() or day_gib < Decimal("0"):
            raise ValueError(f"第 {day_idx + 1} 天存储用量必须为非负有限数值")
        billable_gib = max(day_gib - FREE_TIER_GIB_PER_DAY, Decimal("0"))
        storage_cost += billable_gib * STORAGE_PRICE_PER_GIB_DAY

    non_token_total = web_cost + file_cost + storage_cost
    grand_total = token_cost + non_token_total

    def fmt(val: Decimal) -> str:
        return str(val.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP))

    return {
        "web_search_usd": fmt(web_cost),
        "file_search_usd": fmt(file_cost),
        "storage_usd": fmt(storage_cost),
        "non_token_total_usd": fmt(non_token_total),
        "grand_total_usd": fmt(grand_total)
    }

if __name__ == "__main__":
    # 基线算例: 30天稳定 6 GiB,Token 支出 $100
    baseline = estimate(
        model_usd="100",
        web_calls=20000,
        file_calls=10000,
        daily_total_gib=["6"] * 30
    )
    print("基线支出明细:", baseline)

    # 敏感性分析: Token 支出调整为 $10,非 Token 费用保持不变
    optimized = estimate(
        model_usd="10",
        web_calls=20000,
        file_calls=10000,
        daily_total_gib=["6"] * 30
    )
    print("优化支出明细:", optimized)

5. 架构优化实践:自建检索通道与 APIBox 推理边界

对于已存在成熟检索层(如企业自建向量检索、Elasticsearch 或聚合搜索微服务)的系统,架构上可将检索与大模型推理进行解耦:应用侧自行处理召回初筛,再将结构化摘要递交大模型推理。但必须指出,自建检索本身涉及研发、索引构建、主机托管、持续运维与评测开销,并不能承诺拆出即省。建议已有检索基础设施的团队先进行小样本业务验证,再评估综合成本与收益。

APIBox 平台模型库存与倍率边界

依据 2026 年 11 月 14 日拉取的 APIBox 实时定价接口(版本 a42d372ccf0b5dd13ecf71203521f9d2),平台定价库已列出主流模型的代号与分组计费倍率:

  • gpt-6-astra:包含 gpt-vip-1 分组(倍率 0.1,1 折 / 90% OFF)与 gpt-vip-2 分组(倍率 0.15)。
  • claude-sonnet-5:包含 claude-vip-2 分组(倍率 0.3,3 折 / 70% OFF)与 claude-vip-1 分组(倍率 0.5)。
  • gemini-3.8-flash:包含 gemini-vip 分组(倍率 0.2,2 折 / 80% OFF)。

迁移前核对边界:

  1. 在核验快照中,上述模型条目和分组倍率已列出;这不证明推理调用成功,也不证明原厂托管工具或存储支持。
  2. 不能由 Token 倍率推断外部工具或存储也享相同折扣。
  3. 平台支持微信与支付宝充值,具体价格与支持能力以实时接口和控制台为准。

架构解耦代码:文本推理接入示例

以下代码展示在应用已完成检索的前提下,将提取文本送入模型推理的最小调用逻辑。此为读者自行运行的付费 API 示例,运行前需安装 SDK:

python -m pip install openai
import os
import sys
from openai import OpenAI

api_key = os.environ.get("APIBOX_API_KEY")
if not api_key:
    sys.exit("错误: 未配置 APIBOX_API_KEY 环境变量")

client = OpenAI(
    base_url="https://api.apibox.cc/v1",
    api_key=api_key,
    timeout=60.0,
    max_retries=0
)

# 合成样例数据,非真实个人隐私信息或真实外部检索结果
sample_retrieved_context = (
    "示例订单DEMO-001,状态已发货,承运商顺丰速运,发货节点华东仓。"
)

try:
    response = client.chat.completions.create(
        model="gpt-6-astra",
        messages=[
            {
                "role": "system",
                "content": "你是一个严谨的信息整理助手。只能基于用户提供的上下文回答,禁止臆测。"
            },
            {
                "role": "user",
                "content": f"请简要总结以下订单的状态:\n\n{sample_retrieved_context}"
            }
        ],
        max_completion_tokens=512
    )

    if not response.choices:
        raise RuntimeError("接口返回 choices 为空")

    choice = response.choices[0]
    if choice.finish_reason != "stop":
        raise RuntimeError(f"非预期截断: finish_reason={choice.finish_reason}")

    content = choice.message.content
    if not content or not content.strip():
        raise ValueError("模型生成内容为空或全为空白")

    print("整理结果:\n", content)

    if response.usage:
        p_tokens = response.usage.prompt_tokens if response.usage.prompt_tokens is not None else "unknown"
        c_tokens = response.usage.completion_tokens if response.usage.completion_tokens is not None else "unknown"
        print(f"\n[审计] 输入: {p_tokens}, 输出: {c_tokens}")
    else:
        print("\n[审计] Token 统计数据: unknown")

except Exception as err:
    print(f"调用失败: {err}", file=sys.stderr)
    sys.exit(1)

6. 生产级工程观测指标与降本建议

为了精细化治理非 Token 账单,系统架构应建立结构化的遥测指标:

  1. 结构化日志字段设计:在每笔请求日志中固化成本维度指标,建议包含字段:
    • biller: 供应商标识
    • project: 归属项目
    • tool_type: 触发的工具形态(web_search / file_search / local_rag)
    • tool_calls: 调用计数
    • query_count: 实际派生的子查询数
    • storage_gib_days: 存储体积乘以保留天数(GiB-day)
    • request_id: 链路追踪 ID
    • task_id: 业务任务 ID
    • usage_status: 统计状态(未上报或缺失计为 unknown,严禁将缺失值误记为 0)
  2. 托管工具与自建服务分账:将供应商账单上的托管工具附加费与内部计算、存储基础设施成本隔离审计。
  3. 设置单任务调用上限与生命周期管理:在编排层限制任务搜索次数,并为外部存储资源配置生命周期策略,避免长期无用堆积。
  4. 以任务成功交付成本为基准:评估指标应以 总成本 / 实际验收通过的任务数(Cost per Verified Task)为核心,而非单一的单千 Token 单价。

7. 常见问题解答(FAQ)

托管 Web 搜索与文件检索工具是否在 Token 之外单独计费?

大多数主流模型厂商对托管工具采用独立的调用费、查询费或存储费计量。检索回填到上下文的内容计入输入 Token,但工具执行与模型推理是两个不同的计费维度,并非所有工具或厂商规则完全一致(例如 Google File Search 不收独立的检索查询费)。

降低大模型 Token 单价能否按同等比例降低整个 Agent 的综合运行账单?

不能。以本文设定的重检索算例为例,工具调用与存储等非 Token 费用构成了固定的测算基线。在该特定算例中,即便 Token 支出降低 90%,若工具调用与存储开销维持不变,综合总预算降幅仅为 26.47%,并不存在全量账单的等比缩减。

APIBox 定价库存列出 gpt-6-astra 等模型是否意味着已支持官方托管搜索与向量存储?

不意味着。在核验快照中,定价库仅列出了上述模型条目与分组倍率,这既不证明真实推理调用成功,也未由库存证实支持原厂托管工具或向量存储。已有检索层的团队可将提取出的文本交由 APIBox 模型推理,但在迁移前需独立核对计费与功能边界。


延伸阅读与参考资源:

立即访问 APIBox 控制台 (dashboard.apibox.cc) 注册账户,在控制台核对具体模型分组倍率(如 GPT-6 Astra 支持 gpt-vip-1 1折、Claude Sonnet 5 支持 claude-vip-2 3折、Gemini 3.8 Flash 支持 gemini-vip 2折,支持微信与支付宝充值),并在小批量真实业务样本中验证输出正确率、引用一致性、完成率与综合落地成本。

立即体验,注册后即可使用 30+ 模型,一个 Key 全搞定

免费注册 →