结论先说
- File Search 是 Responses API 内置的托管检索工具,配合向量库(Vector Stores)使用,由 OpenAI 自动完成文档解析、分块、向量化(Embedding)以及语义加关键词混合检索。
- 接入只需四步:上传文件拿到
file_id、创建vector_store并挂载文件、等状态变为completed、在responses.create的tools里加上file_search和vector_store_ids。 - 支持返回精确引用与原始片段:模型回答正文里的
annotations会附带file_citation(来源文件 ID 与文件名);想在调试时拿到命中的原始文本块,请求里加include=["file_search_call.results"]。 - 单文件上限 512 MB(最多 500 万 token),默认按约 800 token 一块、400 token 重叠自动切分,也支持自定义分块大小与按元数据(Metadata)过滤文件。
- 计费分三块:向量库存储费(官方提供前 1 GB 免费额度,超出按日按 GB 计费)、
file_search工具调用费,以及检索出的文本块送进上下文产生的常规输入 token 费。 - 国内免境外卡开通入口:若没有境外银行卡或遇到支付被拒,可在本站通过支付宝、微信支付或 AlipayHK 自助获取兑换码开通 ChatGPT Plus 或 ChatGPT Pro,团队多席位支持联系客服定制 ChatGPT Business 团队版。

图:本站根据 OpenAI 官方文档:File search 整理的示意图
本文根据 OpenAI 官方文档《File search》与官方定价页整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 有多份产品手册、规章制度或技术文档,想在 OpenAI API 里做知识库问答(RAG)却不想自己搭向量数据库的开发者;
- 用过单次文件输入(见 /guides/openai-api-file-inputs-pdf),发现每次把整份大文件塞进请求既慢又费 token 的人;
- 需要在前端展示回答具体引用了哪份文档片段的人。
一、它和直接传文件、自建向量库有什么区别
在决定要不要用 File Search 之前,先看清官方提供的三条路径各自适合什么情况:

图:本站根据 OpenAI 官方文档:File search 与《File inputs》整理的示意图
简单判断:只让模型总结手头一两份 50 MB 以内的 PDF,直接用 input_file 最省事;有一批知识库文档要反复跨文件查细节,用本文的 File Search 最快落地;如果公司数据必须留在自有 PostgreSQL 或本地库里,再自己调 /guides/openai-api-embeddings 建库。
如果你并不打算自己写代码调 API,只是日常办公想把几份资料放进项目空间反复提问,可以直接在 ChatGPT 网页端的项目(Projects)里传文件使用;需要更高对话与文件额度时,可以在本站了解 ChatGPT Plus,注意网页会员订阅与本文讲的开发者 API 账单完全分开计算。
二、完整 Python 接入步骤(创建向量库到发起检索)
前提是已经在平台拿到密钥并配好环境变量 OPENAI_API_KEY(未配置的可先看 /guides/openai-api-key)。
1. 上传文档并创建向量库
先把本地文档传到 Files API(用于检索工具时,purpose 填 assistants),再创建向量库并把文件挂进去。官方 SDK 提供了带轮询的辅助方法,不用自己手写循环等索引完成:
python
from openai import OpenAI
client = OpenAI()
# 1. 创建向量库(Vector Store)
vector_store = client.vector_stores.create(name="产品售后知识库")
# 2. 上传文档并挂入向量库,等待解析与分块完成
with open("return_policy.pdf", "rb") as f:
file_batch = client.vector_stores.file_batches.upload_and_poll(
vector_store_id=vector_store.id,
files=[f],
)
print("批次状态:", file_batch.status)
print("文件统计:", file_batch.file_counts)
只有当状态变成 completed 后,新传的文档才能被搜到。官方支持 PDF、DOCX、TXT、Markdown、JSON 及多种常见代码文件,单文件最大 512 MB、上限 500 万 token。
2. 在 Responses API 里启用 file_search
把刚拿到的 vector_store.id 放进 tools 列表即可(Responses API 的基础结构见 /guides/openai-responses-api):
python
response = client.responses.create(
model="gpt-4o", # 请替换为官方模型页当前推荐的型号
input="拆封后的配件支持几天内退换?有什么限制条件?",
tools=[
{
"type": "file_search",
"vector_store_ids": [vector_store.id],
"max_num_results": 5,
}
],
include=["file_search_call.results"],
)
print(response.output_text)
模型会自动判断当前问题需不需要查库:需要时先生成检索词去向量库拉取片段,再结合片段生成回答。
本站订阅与团队开通提示:如果你在国内遇到银行卡被拒或急需提升对话与推理配额,可前往本站 ChatGPT Plus 充值说明页 或 ChatGPT Pro 5x/20x 充值页 自助获取卡密完成开通(全程无需交出账号密码,可开增值税发票);企业多成员协作可直接查看 ChatGPT Business 团队定制方案。
三、怎么读取来源引用(Annotations)与原始片段
返回结果里的 response.output 通常包含两类关键项:
file_search_call:记录这次工具调用的 ID、状态;如果请求时加了include=["file_search_call.results"],这里还会列出命中的原始文本块、得分和所属文件名,排查“为什么答偏了”全靠看这一项。message(模型回答):在正文内容块的annotations数组里,每处引用的类型都是file_citation,包含file_id、filename和字符位置索引。前端可以据此渲染“参考来源:《xxx.pdf》”。
四、控制成本与精度的三个常用参数
- 限制召回块数(
max_num_results):检索出来的每一块文本都会塞进模型上下文按输入 token 计费。把max_num_results调小(例如设为 4 到 8)能明显降低延迟和单次 token 开销,但设得太小可能漏掉跨段落信息。 - 元数据过滤(
filters):给向量库里的文件打上键值对属性(如category: "billing"或年份),提问时在file_search工具里传filters条件,只搜指定范围的文档,减少无关干扰。 - 设置过期清理(
expires_after):如果是给临时会话建的向量库,创建时设好闲置自动过期天数,防止废弃库一直占着容量产生按日存储费。各档位具体单价请核对 /guides/openai-api-price-official-table。
常见问题
问:文档刚传上去就提问,为什么模型说找不到相关内容?
大PDF解析、切块和算向量需要时间。文件还在 in_progress 状态时搜不到,务必用 upload_and_poll 或先查 vector_stores.files 确认状态已是 completed,若变成 failed 需检查文件是否加密损坏或超出 500 万 token 上限。
问:扫描版纯图片 PDF 能用 File Search 检索吗?
File Search 依赖从文件里提取出的文本建索引;纯扫描件若没有内嵌文字层,提取出的文本为空就无法检索。这类带大量版面图像的少页数 PDF,改用 input_file 走视觉解析更合适。
问:删除向量库(Vector Store)会把原始上传的文件一起删掉吗?
不会。向量库只是索引容器,删掉向量库只会停止继续计收该库的向量存储费,Files API 里的原始文件仍保留在后台,需要彻底清理时另调 client.files.delete。
问:国内没有境外信用卡,怎么开通或续费 ChatGPT Plus / Pro?
答:可在本站使用支付宝、微信支付或 AlipayHK 下单获取卡密自助兑换(支持 ChatGPT Plus、Pro 5x 可覆盖档 与 Pro 5x 空白号档),实时价格、兑换前提与售后规则(掉订阅按剩余天数折退,封号不在质保范围)以对应页面说明为准。
相关教程
参考资料
- OpenAI 官方文档:File search — https://developers.openai.com/api/docs/guides/tools-file-search
- OpenAI 官方定价页 — https://developers.openai.com/api/docs/pricing
0 条评论
还没有评论,来抢沙发~