文件搜索 | OpenAI API

文件搜索是一个可用的工具，位于 Responses API。它使模型能够通过语义和关键词搜索，在之前上传的文件构成的知识库中检索信息。通过创建向量存储并上传文件，你可以让模型访问这些知识库或 vector_stores.

要了解更多关于向量存储和语义搜索的工作原理，请参阅我们的检索指南.

这是一个由 OpenAI 托管的工具，这意味着您无需在本地实现代码即可处理其执行。当模型决定使用该工具时，它会自动调用该工具，从您的文件中检索信息，并返回输出。

如何使用

在将文件搜索与 Responses API 结合使用之前，您需要在向量存储中建立知识库并上传相关文件。

创建向量存储并上传文件

按照以下步骤创建向量存储并上传文件。您可以使用此示例文件 or upload your own.

将文件上传到 File API

上传文件

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import requests
from io import BytesIO
from openai import OpenAI

client = OpenAI()

def create_file(client, file_path):
    if file_path.startswith("http://") or file_path.startswith("https://"):
        # Download the file content from the URL
        response = requests.get(file_path)
        file_content = BytesIO(response.content)
        file_name = file_path.split("/")[-1]
        file_tuple = (file_name, file_content)
        result = client.files.create(
            file=file_tuple,
            purpose="assistants"
        )
    else:
        # Handle local file path
        with open(file_path, "rb") as file_content:
            result = client.files.create(
                file=file_content,
                purpose="assistants"
            )
    print(result.id)
    return result.id

# Replace with your own file path or URL
file_id = create_file(client, "https://cdn.openai.com/API/docs/deep_research_blog.pdf")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import fs from "fs";
import OpenAI from "openai";
const openai = new OpenAI();

async function createFile(filePath) {
  let result;
  if (filePath.startsWith("http://") || filePath.startsWith("https://")) {
    // Download the file content from the URL
    const res = await fetch(filePath);
    const buffer = await res.arrayBuffer();
    const urlParts = filePath.split("/");
    const fileName = urlParts[urlParts.length - 1];
    const file = new File([buffer], fileName);
    result = await openai.files.create({
      file: file,
      purpose: "assistants",
    });
  } else {
    // Handle local file path
    const fileContent = fs.createReadStream(filePath);
    result = await openai.files.create({
      file: fileContent,
      purpose: "assistants",
    });
  }
  return result.id;
}

// Replace with your own file path or URL
const fileId = await createFile(
  "https://cdn.openai.com/API/docs/deep_research_blog.pdf"
);

console.log(fileId);

创建向量存储

python

1
2
3
4
vector_store = client.vector_stores.create(
    name="knowledge_base"
)
print(vector_store.id)

1
2
3
4
const vectorStore = await openai.vectorStores.create({
    name: "knowledge_base",
});
console.log(vectorStore.id);

将文件添加到向量存储

python

1
2
3
4
5
result = client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file_id
)
print(result)

1
2
3
4
5
6
await openai.vectorStores.files.create(
    vectorStore.id,
    {
        file_id: fileId,
    }
});

检查状态

运行此代码，直到文件准备就绪（即状态为 completed).

检查状态

python

1
2
3
4
result = client.vector_stores.files.list(
    vector_store_id=vector_store.id
)
print(result)

1
2
3
4
const result = await openai.vectorStores.files.list({
    vector_store_id: vectorStore.id,
});
console.log(result);

知识库设置完成后，您可以将 file_search 工具包含在模型可用的工具列表中，并同时提供需要进行搜索的向量存储列表。

文件搜索工具

python

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI
client = OpenAI()

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
    model: "gpt-5.5",
    input: "What is deep research by OpenAI?",
    tools: [
        {
            type: "file_search",
            vector_store_ids: ["<vector_store_id>"],
        },
    ],
});
console.log(response);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
using OpenAI.Responses;

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
OpenAIResponseClient client = new(model: "gpt-5.5", apiKey: key);

ResponseCreationOptions options = new();
options.Tools.Add(ResponseTool.CreateFileSearchTool(["<vector_store_id>"]));

OpenAIResponse response = (OpenAIResponse)client.CreateResponse([
    ResponseItem.CreateUserMessageItem([
        ResponseContentPart.CreateInputTextPart("What is deep research by OpenAI?"),
    ]),
], options);

Console.WriteLine(response.GetOutputText());

当模型调用此工具时，您将收到一个包含多个输出的响应：

A file_search_call output item，其中包含文件搜索调用的 ID。
A message output item，其中包含模型的响应以及文件引用。

文件搜索响应

json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "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 用量和延迟，但可能会降低回答质量。

限制结果数量

python

1
2
3
4
5
6
7
8
9
10
response = client.responses.create(
    model="gpt-4.1",
    input="What is deep research by OpenAI?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["<vector_store_id>"],
        "max_num_results": 2
    }]
)
print(response)

1
2
3
4
5
6
7
8
9
10
const response = await openai.responses.create({
    model: "gpt-4.1",
    input: "What is deep research by OpenAI?",
    tools: [{
        type: "file_search",
        vector_store_ids: ["<vector_store_id>"],
        max_num_results: 2,
    }],
});
console.log(response);

在响应中包含搜索结果

虽然您可以在输出文本中看到注解（对文件的引用），但文件搜索调用默认不会返回搜索结果。

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

包含搜索结果

python

1
2
3
4
5
6
7
8
9
10
response = client.responses.create(
    model="gpt-4.1",
    input="What is deep research by OpenAI?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["<vector_store_id>"]
    }],
    include=["file_search_call.results"]
)
print(response)

1
2
3
4
5
6
7
8
9
10
const response = await openai.responses.create({
    model: "gpt-4.1",
    input: "What is deep research by OpenAI?",
    tools: [{
        type: "file_search",
        vector_store_ids: ["<vector_store_id>"],
    }],
    include: ["file_search_call.results"],
});
console.log(response);

元数据过滤

您可以根据文件的元数据过滤搜索结果。有关更多详细信息，请参阅我们的检索指南, 内容包括：

操作指南在向量存储文件上设置属性
操作指南定义过滤器

元数据过滤

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
response = client.responses.create(
    model="gpt-4.1",
    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)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const response = await openai.responses.create({
    model: "gpt-4.1",
    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"]
        }
    }]
});
console.log(response);

支持的文件

For text/ MIME 类型，编码必须是以下之一 utf-8, utf-16, or 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 可用性	速率限制	备注
响应 Chat Completions 助手	层级 1 100 RPM 第 2 层和第 3 层 500 RPM 第4层和第5层 1000 RPM	定价 ZDR 和数据驻留

API 可用性

速率限制

备注

响应

Chat Completions

助手

层级 1
100 RPM

第 2 层和第 3 层
500 RPM

第4层和第5层
1000 RPM

定价
 ZDR 和数据驻留

推荐

入门

核心概念

Apps SDK

工具

运行与扩展

评估

实时与音频

模型优化

专业模型

正式上线

旧版 API

资源

入门指南

使用 Codex

配置

管理

自动化

学习

发布

核心概念

规划

构建

部署

转化应用

指南

资源

指南

文件上传

API

衡量

广告主 API

API 参考

最新

主题

主题

贡献

分类

主题

项目

活动

如何使用

将文件上传到 File API

创建向量存储

将文件添加到向量存储

检查状态

检索自定义

限制结果数量

在响应中包含搜索结果

元数据过滤

支持的文件

使用说明