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 运行生命周期通常跨越四个层级,各层级计量逻辑相互独立:
- 终端用户任务(User Task):用户触发的完整业务流程(例如生成一份行业竞品综述)。一个任务往往包含多轮规划与多次工具调用。
- 模型推理请求(API Request):向网关发起的单次 HTTP 请求,产生常规 prompt tokens、completion tokens 及思考推理 tokens。
- 托管工具调用与查询(Tool Calls / Queries):模型在规划执行阶段调用的外部托管能力。各厂商对“调用次数(Call)”与“派生查询数(Query)”的计量标准不同。
- 持久化索引存储(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:按搜索动作计量
- 搜索费用: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 动作计) | 本文未评估独立文件检索/存储产品 | 本文未评估独立文件检索/存储产品 | 按对应模型输入规则计费 |
| 项目月享 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.00 | 58.82% |
| File Search (10,000 calls) | $25.00 | $25.00 | 7.35% |
| Vector Storage (6 GiB, 30天) | $15.00 | $15.00 | 4.41% |
| 非 Token 开销小计 | $240.00 | $240.00 | 70.59% |
| 模型 Token 支出 (含回填) | $100.00 | $10.00 | 29.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)。
迁移前核对边界:
- 在核验快照中,上述模型条目和分组倍率已列出;这不证明推理调用成功,也不证明原厂托管工具或存储支持。
- 不能由 Token 倍率推断外部工具或存储也享相同折扣。
- 平台支持微信与支付宝充值,具体价格与支持能力以实时接口和控制台为准。
架构解耦代码:文本推理接入示例
以下代码展示在应用已完成检索的前提下,将提取文本送入模型推理的最小调用逻辑。此为读者自行运行的付费 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 账单,系统架构应建立结构化的遥测指标:
- 结构化日志字段设计:在每笔请求日志中固化成本维度指标,建议包含字段:
biller: 供应商标识project: 归属项目tool_type: 触发的工具形态(web_search/file_search/local_rag)tool_calls: 调用计数query_count: 实际派生的子查询数storage_gib_days: 存储体积乘以保留天数(GiB-day)request_id: 链路追踪 IDtask_id: 业务任务 IDusage_status: 统计状态(未上报或缺失计为unknown,严禁将缺失值误记为0)
- 托管工具与自建服务分账:将供应商账单上的托管工具附加费与内部计算、存储基础设施成本隔离审计。
- 设置单任务调用上限与生命周期管理:在编排层限制任务搜索次数,并为外部存储资源配置生命周期策略,避免长期无用堆积。
- 以任务成功交付成本为基准:评估指标应以
总成本 / 实际验收通过的任务数(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 全搞定
免费注册 →