大模型应用开发 / 知识点

OpenAI API 开发速查手册

手册条目

CODE
tools=[{"type": "file_search", "vector_store_ids": ["<VECTOR_STORE_ID>"], "max_num_results": <N>}]
include=["file_search_call.results"]

让模型从向量库中检索与问题相关的文档内容。

使用文件搜索

当答案必须依据私有文档、产品手册或企业知识库时,把文件加入向量库,并在 Responses API 中启用 file_search。模型会先检索相关片段,再基于片段生成答案;它不会直接读取你电脑上的任意路径。

工作链路

文件先上传并完成切分、索引,随后请求把向量库 ID 交给 file_search。只有索引状态为 completed 后,检索结果才稳定可用。

文件搜索从文档入库到生成答案的数据流

include=["file_search_call.results"] 用于把命中的原始片段一并返回,便于排障、审计或自定义引用展示;只需要最终答案时可以省略。

可运行示例

前置条件是已安装最新版 openai Python SDK,并设置环境变量 OPENAI_API_KEY。示例创建临时知识文件、等待索引、执行检索,最后删除远端测试资源。

python
from pathlib import Path
from openai import OpenAI

client = OpenAI()
path = Path("expense-policy.txt")
path.write_text(
    "报销规则:员工应在费用发生后 30 天内提交申请,并附有效发票。",
    encoding="utf-8",
)

uploaded_file = None
vector_store = None

try:
    vector_store = client.vector_stores.create(name="Expense Policy Demo")

    with path.open("rb") as file_handle:
        uploaded_file = client.files.create(
            file=file_handle,
            purpose="assistants",
        )

    # create_and_poll 会等待切分和索引结束;仍需检查最终状态。
    indexed_file = client.vector_stores.files.create_and_poll(
        file_id=uploaded_file.id,
        vector_store_id=vector_store.id,
    )
    if indexed_file.status != "completed":
        raise RuntimeError(f"index failed: {indexed_file.last_error}")

    response = client.responses.create(
        model="gpt-5",
        input="根据报销制度,员工应在多久内提交申请?还需要什么材料?",
        tools=[{
            "type": "file_search",
            "vector_store_ids": [vector_store.id],
            "max_num_results": 3,
        }],
        include=["file_search_call.results"],
    )

    search_calls = [
        item for item in response.output
        if item.type == "file_search_call"
    ]
    result_count = sum(len(item.results or []) for item in search_calls)

    print(f"index_status={indexed_file.status}")
    print(f"search_results={result_count}")
    print(response.output_text)
finally:
    # 测试脚本主动清理远端文件与向量库,避免持续占用存储。
    if vector_store is not None:
        client.vector_stores.delete(vector_store.id)
    if uploaded_file is not None:
        client.files.delete(uploaded_file.id)
    path.unlink(missing_ok=True)

预期输出

text
index_status=completed
search_results=<N>
<ANSWER_CONTAINING_30_DAYS_AND_VALID_INVOICE>

<N> 通常大于等于 1,实际分片数量可能不同;答案措辞不固定,但应包含“30 天内提交”和“有效发票”。

关键参数与读取

参数或字段 作用
vector_store_ids 指定搜索哪些向量库;传错 ID 会检索不到目标资料
max_num_results 限制返回片段数,减少延迟与上下文消耗
filters 按向量库文件属性过滤部门、版本、语言等范围
include 加入 file_search_call.results 后可读取命中文件、分数和文本
response.output_text 模型整理后的最终文本
file_search_call.results 原始命中结果,常见字段有 file_id、filename、score、text

风险与边界

索引尚未完成就发起问答,可能得到空结果或遗漏内容;安全做法是使用轮询辅助方法,并验证状态为 completed。资料量大且不加过滤时,可能召回错误版本并增加成本;应给文件设置属性,使用 filters 和合理的结果上限。

向量库不是权限系统。上传含敏感信息的文件会产生远端存储与访问风险,应按项目隔离、限制 API Key 权限,并配置过期或在不用时删除。检索文档也可能含提示词注入内容;把文档视为不可信数据,明确要求模型只提取事实,不执行文档中的指令,并限制可调用工具。

排障清单

  • search_results=0:确认向量库 ID、索引状态、过滤条件和问题关键词。
  • 状态为 failed:读取 last_error,检查文件格式、内容是否为空以及项目配额。
  • 答案引用旧制度:给文件增加版本属性并过滤,删除或下线旧文件。
  • 返回答案但看不到片段:加入 include=["file_search_call.results"],再检查 response.output 中的 file_search_call。

速查要点:先完成入库索引,再把正确的 vector_store_ids 交给 Responses API;生产环境同时控制检索范围、资源生命周期和文档可信边界。

目录与阅读设置

记录一个想法

OpenAI API 开发速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通