如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

文件搜索

让模型在生成回复前,从您的文件中查找相关信息。

文件搜索是 Responses API 提供的一项工具。 模型可以通过语义搜索和关键词搜索,从已上传的文件组成的知识库中检索信息。 您可以创建向量存储并将文件上传到其中,让模型访问这些知识库(即 vector_stores),以补充模型已有的知识。

要了解向量存储和语义搜索的工作原理,请参阅检索指南。

文件搜索由 OpenAI 托管,您无需编写代码来执行搜索。 当模型决定使用这项工具时,它会自动调用工具,从您的文件中检索信息并返回结果。

使用方法

在 Responses API 中使用文件搜索之前,您需要先在向量存储中建立知识库,并将文件上传到其中。

知识库准备就绪后,您可以将 file_search 添加到模型可用的工具列表中,并指定要搜索的向量存储列表。

文件搜索工具
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.2-astra",
    input="What is deep research by OpenAI?",
    tools=[{"type": "file_search", "vector_store_ids": ["<vector_store_id>"]}],
)
print(response)

当模型调用这项工具时,您收到的响应会包含多个输出项:

  1. file_search_call 输出项包含本次文件搜索调用的 ID。
  2. message 输出项包含模型的回复及相应的文件引用。
文件搜索响应
{
  "output": [
    {
      "type": "file_search_call",
      "id": "fs_67c09ccea8c48191ade9367e3ba71515",
      "status": "completed",
      "queries": ["What is deep research?"],
      "search_results": null
    },
    {
      "id": "msg_67c09cd3091c819185af2be5d13d87de",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Deep research is a sophisticated capability that allows for extensive inquiry and synthesis of information across various domains. It is designed to conduct multi-step research tasks, gather data from multiple online sources, and provide comprehensive reports similar to what a research analyst would produce. This functionality is particularly useful in fields requiring detailed and accurate information...",
          "annotations": [
            {
              "type": "file_citation",
              "index": 992,
              "file_id": "file-2dtbBZdjtDKS8eqWxqbgDi",
              "filename": "deep_research_blog.pdf"
            },
            {
              "type": "file_citation",
              "index": 992,
              "file_id": "file-2dtbBZdjtDKS8eqWxqbgDi",
              "filename": "deep_research_blog.pdf"
            },
            {
              "type": "file_citation",
              "index": 1176,
              "file_id": "file-2dtbBZdjtDKS8eqWxqbgDi",
              "filename": "deep_research_blog.pdf"
            },
            {
              "type": "file_citation",
              "index": 1176,
              "file_id": "file-2dtbBZdjtDKS8eqWxqbgDi",
              "filename": "deep_research_blog.pdf"
            }
          ]
        }
      ]
    }
  ]
}

自定义检索

限制结果数量

在 Responses API 中使用文件搜索工具时,您可以指定要从向量存储中检索多少条结果。减少结果数量有助于降低 Token 用量并缩短延迟,但也可能降低回答质量。

限制结果数量
response = client.responses.create(
    model="gpt-6.2-astra",
    input="What is deep research by OpenAI?",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": ["<vector_store_id>"],
            "max_num_results": 2,
        }
    ],
)
print(response)

在响应中包含搜索结果

输出文本中的注释会标明引用的文件,但文件搜索调用默认不会返回搜索结果。

要在响应中包含搜索结果,您可以在创建响应时使用 include 参数。

包含搜索结果
response = client.responses.create(
    model="gpt-6.2-astra",
    input="What is deep research by OpenAI?",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": ["<vector_store_id>"],
        }
    ],
    include=["file_search_call.results"],
)
print(response)

按元数据筛选

您可以根据文件的元数据筛选搜索结果。有关详细信息,请参阅检索指南,其中介绍了以下操作:

按元数据筛选
response = client.responses.create(
    model="gpt-6.2-astra",
    input="What is deep research by OpenAI?",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": ["<vector_store_id>"],
            "filters": {
                "type": "in",
                "key": "category",
                "value": ["blog", "announcement"],
            },
        }
    ],
)
print(response)

支持的文件格式

对于以 text/ 开头的 MIME 类型,文件编码必须是 utf-8、utf-16 或 ascii。

文件格式 MIME 类型
.c text/x-c
.cpp text/x-c++
.cs text/x-csharp
.css text/css
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.go text/x-golang
.html text/html
.java text/x-java
.js text/javascript
.json application/json
.md text/markdown
.pdf application/pdf
.php text/x-php
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.py text/x-python
.py text/x-script.python
.rb text/x-ruby
.sh application/x-sh
.tex text/x-tex
.ts application/typescript
.txt text/plain

使用说明

API 支持情况速率限制备注

Build
500 RPM

Launch 和 Grow
1000 RPM

定价
零数据保留(ZDR)和数据驻留