如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

檔案搜尋

讓模型在產生回應前,先從你的檔案中搜尋相關資訊。

檔案搜尋是 Responses API 提供的工具。 模型可以透過語意搜尋和關鍵字搜尋,從先前上傳的檔案所構成的知識庫中擷取資訊。 你可以建立向量儲存區並將檔案上傳至其中,讓模型存取這些知識庫(即 vector_stores),補充模型原有的知識。

如需進一步瞭解向量儲存區和語意搜尋的運作方式,請參閱檢索指南。

這項工具由 OpenAI 託管,你不必自行撰寫程式碼來執行工具。 模型決定使用這項工具時,會自動呼叫工具,從你的檔案中擷取資訊並傳回結果。

使用方式

透過 Responses API 使用檔案搜尋前,你需要先在向量儲存區中建立知識庫,並將檔案上傳至該儲存區。

知識庫設定完成後,你可以將 file_search 加入模型可用的工具清單,並指定要搜尋哪些向量儲存區。

檔案搜尋工具
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-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-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-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-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)

支援的檔案格式

如果檔案的 MIME 類型以 text/ 開頭,檔案編碼必須是 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 與資料駐留