OpenAI 文件搜索

文件搜索是 Responses API 提供的工具。它通过语义搜索与关键词搜索，让模型从已上传文件构成的知识库中检索信息。创建向量存储并上传文件后，就能让模型访问这些知识库（vector_stores），补充模型原有的知识。

关于向量存储与语义搜索的工作原理，参见检索指南。

这是由 OpenAI 管理的托管工具，你不必自行编写处理工具执行的代码。当模型决定使用它时，会自动调用工具、从文件中取回信息并返回输出。

如何使用

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

创建向量存储并上传文件

按以下步骤创建向量存储并上传文件。可以使用这个示例文件，也可以使用自己的文件。

将文件上传到 Files API

来源示例1（javascript）

// [中文] 把文件上传到Files API并取得文件ID；网络下载与本地读取分支以本语言原例为准。
// [中文] 原例中Java、Ruby使用user_data，JavaScript、Python、Go使用assistants；保留各语言原参数，不擅自统一。
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://")) {
    // [中文] 先从URL下载文件内容，再封装为可上传文件。
    // 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;
}

// [中文] 替换为自己的文件路径或URL。
// 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);

来源示例2（python）

## [中文] 把文件上传到Files API并取得文件ID；网络下载与本地读取分支以本语言原例为准。
## [中文] 原例中Java、Ruby使用user_data，JavaScript、Python、Go使用assistants；保留各语言原参数，不擅自统一。
from io import BytesIO

import requests
from openai import OpenAI

client = OpenAI()


def create_file(client, file_path):
    if file_path.startswith(("http://", "https://")):
        response = requests.get(file_path, timeout=30)
        # [中文] 在上传前检查下载请求是否成功。
        response.raise_for_status()
        file_content = BytesIO(response.content)
        file_name = file_path.rsplit("/", 1)[-1]
        result = client.files.create(
            file=(file_name, file_content),
            purpose="assistants",
        )
    else:
        with open(file_path, "rb") as file_content:
            result = client.files.create(
                file=file_content,
                purpose="assistants",
            )
    return result.id


file_id = create_file(
    client,
    "https://cdn.openai.com/API/docs/deep_research_blog.pdf",
)
print(file_id)

来源示例3（go）

// [中文] 把文件上传到Files API并取得文件ID；网络下载与本地读取分支以本语言原例为准。
// [中文] 原例中Java、Ruby使用user_data，JavaScript、Python、Go使用assistants；保留各语言原参数，不擅自统一。
package main

import (
    "context"
    "fmt"
    "os"

    "github.com/openai/openai-go/v3"
)

func main() {
    file, err := os.Open("customer_policies.txt")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    client := openai.NewClient()
    result, err := client.Files.New(context.Background(), openai.FileNewParams{
        File:    openai.File(file, "customer_policies.txt", "text/plain"),
        Purpose: openai.FilePurposeAssistants,
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(result.ID)
}

来源示例4（java）

// [中文] 把文件上传到Files API并取得文件ID；网络下载与本地读取分支以本语言原例为准。
// [中文] 原例中Java、Ruby使用user_data，JavaScript、Python、Go使用assistants；保留各语言原参数，不擅自统一。
// [中文] Java原例为API调用片段，需已有client及适用的外层类或方法；未作为独立Java文件编译。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.FileCreateParams;
import com.openai.models.files.FilePurpose;
import java.nio.file.Path;

var file =
    client
        .files()
        .create(
            FileCreateParams.builder()
                .file(Path.of(System.getenv("OPENAI_EXAMPLE_FILE_PATH")))
                .purpose(FilePurpose.USER_DATA)
                .build());

System.out.println(file.id());

来源示例5（ruby）

## [中文] 把文件上传到Files API并取得文件ID；网络下载与本地读取分支以本语言原例为准。
## [中文] 原例中Java、Ruby使用user_data，JavaScript、Python、Go使用assistants；保留各语言原参数，不擅自统一。
require "openai"
require "pathname"

client = OpenAI::Client.new
file = Pathname("customer_policies.txt")
uploaded = client.files.create(file: file, purpose: :user_data)
puts(uploaded.id)

创建向量存储

来源示例6（javascript）

程序中的自然语言译释32：

知识库（存储名称，保留代码原值）。

// [中文] 创建空向量存储并记录ID；创建存储本身不会上传或完成文件索引。
const vectorStore = await openai.vectorStores.create({
  name: "knowledge_base",
});
console.log(vectorStore.id);

来源示例7（python）

本段复用的中文释义：译释32。

## [中文] 创建空向量存储并记录ID；创建存储本身不会上传或完成文件索引。
vector_store = client.vector_stores.create(name="knowledge_base")
print(vector_store.id)

来源示例8（go）

本段复用的中文释义：译释32。

// [中文] 创建空向量存储并记录ID；创建存储本身不会上传或完成文件索引。
package main

import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
)

func main() {
    client := openai.NewClient()
    vectorStore, err := client.VectorStores.New(context.Background(), openai.VectorStoreNewParams{
        Name: openai.String("knowledge_base"),
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(vectorStore.ID)
}

来源示例9（java）

程序中的自然语言译释31：

产品文档。

// [中文] 创建空向量存储并记录ID；创建存储本身不会上传或完成文件索引。
// [中文] Java原例为API调用片段，需已有client及适用的外层类或方法；未作为独立Java文件编译。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.vectorstores.VectorStoreCreateParams;

var store =
    client
        .vectorStores()
        .create(VectorStoreCreateParams.builder().name("Product docs").build());

System.out.println(store.id());

来源示例10（ruby）

本段复用的中文释义：译释31。

## [中文] 创建空向量存储并记录ID；创建存储本身不会上传或完成文件索引。
require "openai"

client = OpenAI::Client.new
store = client.vector_stores.create(name: "Product docs")
puts(store.id)

将文件加入向量存储

来源示例11（javascript）

// [中文] 用已有文件ID把上传文件加入指定向量存储，文件处理是异步的，之后需要检查状态。
// [中文] 沿用前面创建的vectorStore和上传得到的fileId。
// Use vectorStore and fileId from the earlier create and upload steps.
await openai.vectorStores.files.create(vectorStore.id, {
  file_id: fileId,
});

来源示例12（python）

Python异常信息译释：File indexing ended with status 表示“文件索引结束时的状态为……”。

## [中文] 把已有文件加入向量存储，并由create_and_poll等待索引结束；状态不是completed时抛出异常。
result = client.vector_stores.files.create_and_poll(
    vector_store_id=vector_store.id,
    file_id=file_id,
)
if result.status != "completed":
    raise RuntimeError(f"File indexing ended with status: {result.status}")
print(result)

来源示例13（go）

// [中文] 用已有文件ID把上传文件加入指定向量存储，文件处理是异步的，之后需要检查状态。
package main

import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
)

func main() {
    client := openai.NewClient()
    file, err := client.VectorStores.Files.New(context.Background(), "<vector_store_id>", openai.VectorStoreFileNewParams{
        FileID: "file_abc123",
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(file.ID)
}

来源示例14（java）

// [中文] 用已有文件ID把上传文件加入指定向量存储，文件处理是异步的，之后需要检查状态。
// [中文] Java原例为API调用片段，需已有client及适用的外层类或方法；未作为独立Java文件编译。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.vectorstores.files.FileCreateParams;

String vectorStoreId = "<vector_store_id>";

String fileId = "file_abc123";

var file =
    client
        .vectorStores()
        .files()
        .create(vectorStoreId, FileCreateParams.builder().fileId(fileId).build());

System.out.println(file.id());

来源示例15（ruby）

## [中文] 用已有文件ID把上传文件加入指定向量存储，文件处理是异步的，之后需要检查状态。
require "openai"

client = OpenAI::Client.new
file = client.vector_stores.files.create("<vector_store_id>", file_id: "file_abc123")
puts(file.id)

检查状态

反复检查文件状态，直到可供使用，即状态变为 completed。Python示例先等待索引完成，再轮询列表直至目标文件可见，最长等待60秒；其他语言的列表片段为单次调用，需由调用端安排等待与状态检查。

来源示例16（javascript）

// [中文] 沿用前面创建的vectorStore，列出文件并输出result.data；这是单次列表调用。
// Use vectorStore from the earlier create step.
const result = await openai.vectorStores.files.list(vectorStore.id);
console.log(result.data);

来源示例17（python）

Python异常信息译释：The indexed file is not visible in the listing yet. 表示“已建立索引的文件尚未在列表中可见”。

## [中文] 索引完成后列表可能延迟可见；每秒检查一次目标文件是否以completed状态出现在结果中，最多等待60秒。
## [中文] 超过期限仍未看到目标文件时抛出TimeoutError；不能只凭列表请求成功就认定文件可搜索。
import time

## Listing visibility can lag behind completed indexing.
deadline = time.monotonic() + 60
while True:
    result = client.vector_stores.files.list(vector_store_id=vector_store.id)
    if any(file.id == file_id and file.status == "completed" for file in result.data):
        break
    if time.monotonic() >= deadline:
        raise TimeoutError("The indexed file is not visible in the listing yet.")
    time.sleep(1)
print(result)

来源示例18（go）

// [中文] 列出向量存储中的文件并查看状态；单次调用不是轮询循环，须等待目标文件completed后再搜索。
package main

import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
)

func main() {
    client := openai.NewClient()
    files, err := client.VectorStores.Files.List(context.Background(), "<vector_store_id>", openai.VectorStoreFileListParams{})
    if err != nil {
        panic(err)
    }
    fmt.Println(files.Data)
}

来源示例19（java）

// [中文] 列出向量存储中的文件并查看状态；单次调用不是轮询循环，须等待目标文件completed后再搜索。
// [中文] Java原例为API调用片段，需已有client及适用的外层类或方法；未作为独立Java文件编译。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

String vectorStoreId = "<vector_store_id>";

System.out.println(client.vectorStores().files().list(vectorStoreId).data());

来源示例20（ruby）

## [中文] 列出向量存储中的文件并查看状态；单次调用不是轮询循环，须等待目标文件completed后再搜索。
require "openai"

client = OpenAI::Client.new
files = client.vector_stores.files.list("<vector_store_id>")
puts(files.data&.map(&:status))

知识库准备完成后，在模型可使用的工具列表中加入 file_search，并提供需要搜索的向量存储 ID 列表。

来源示例21（javascript）

程序中的自然语言译释33：

OpenAI的深度研究（deep research）是什么？

// [中文] 在Responses请求中启用file_search并指定向量存储ID，让模型依据知识库回答深度研究（deep research）的问题。
import OpenAI from "openai";
const openai = new OpenAI();

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

来源示例22（python）

本段复用的中文释义：译释33。

## [中文] 在Responses请求中启用file_search并指定向量存储ID，让模型依据知识库回答深度研究（deep research）的问题。
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)

来源示例23（go）

本段复用的中文释义：译释33。

// [中文] 在Responses请求中启用file_search并指定向量存储ID，让模型依据知识库回答深度研究（deep research）的问题。
package main

import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/responses"
)

func main() {
    client := openai.NewClient()
    response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
        Model: "gpt-6-astra",
        Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is deep research by OpenAI?")},
        Tools: []responses.ToolUnionParam{responses.ToolParamOfFileSearch([]string{"<vector_store_id>"})},
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(response)
}

来源示例24（java）

本段复用的中文释义：译释33。

// [中文] 在Responses请求中启用file_search并指定向量存储ID，让模型依据知识库回答深度研究（deep research）的问题。
// [中文] Java原例为API调用片段，需已有client及适用的外层类或方法；未作为独立Java文件编译。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;

String vectorStoreId = "<vector_store_id>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What is deep research by OpenAI?")
        .addFileSearchTool(List.of(vectorStoreId))
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

来源示例25（csharp）

本段复用的中文释义：译释33。

// [中文] 在Responses请求中启用file_search并指定向量存储ID，让模型依据知识库回答深度研究（deep research）的问题。
using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
string vectorStoreId = "<vector_store_id>";
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
    ResponseTool.CreateFileSearchTool([vectorStoreId])
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("What is deep research by OpenAI?")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

来源示例26（ruby）

本段复用的中文释义：译释33。

## [中文] 在Responses请求中启用file_search并指定向量存储ID，让模型依据知识库回答深度研究（deep research）的问题。
require "openai"

openai = OpenAI::Client.new

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

puts(response)

当模型调用该工具时，响应包含多个输出项：

file_search_call：包含文件搜索调用的 ID。
message：包含模型回答及其文件引用。

来源示例27（json）：以下保留协议载荷、配置、返回示意或语法定义；省略号及片段不代表完整可运行程序。

程序中的自然语言译释34：

什么是深度研究（deep research）？

程序中的自然语言译释35：

深度研究（deep research）是一项复杂的能力，可以对多个领域开展深入调查并综合信息。它旨在执行多步骤研究任务，从多个在线来源收集数据，生成类似研究分析师撰写的综合报告。这项功能特别适合需要详尽、准确信息的领域……

{
  "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"
            }
          ]
        }
      ]
    }
  ]
}

响应字段说明：上面的官方指南原例使用 search_results: null，本译文保留其原始字段。当前Responses接口参考将文件搜索调用的结果字段定义为 results（可选数组或 null）；下面请求实际检索结果时使用的路径是 file_search_call.results。编写当前响应解析逻辑时，应以接口参考的 results 为准，不应把指南原例中的 search_results 当成当前字段名。

自定义检索

限制结果数量

使用 Responses API 文件搜索工具时，可以自定义从向量存储中取回的结果数量。这可以减少词元用量和延迟，但也可能降低回答质量。

来源示例28（javascript）

本段复用的中文释义：译释33。

// [中文] 将文件搜索结果上限设为2，以减少取回内容；较少结果可能影响回答质量。
const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: "What is deep research by OpenAI?",
  tools: [
    {
      type: "file_search",
      vector_store_ids: ["<vector_store_id>"],
      // highlight-start
      // [中文] 最多取回2条搜索结果。
      max_num_results: 2,
      // highlight-end
    },
  ],
});
console.log(response);

来源示例29（python）

本段复用的中文释义：译释33。

## [中文] 将文件搜索结果上限设为2，以减少取回内容；较少结果可能影响回答质量。
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>"],
            # highlight-start
            # [中文] 最多取回2条搜索结果。
            "max_num_results": 2,
            # highlight-end
        }
    ],
)
print(response)

来源示例30（go）

本段复用的中文释义：译释33。

// [中文] 将文件搜索结果上限设为2，以减少取回内容；较少结果可能影响回答质量。
package main

import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/responses"
)

func main() {
    client := openai.NewClient()
    tool := responses.ToolParamOfFileSearch([]string{"<vector_store_id>"})
    tool.OfFileSearch.MaxNumResults = openai.Int(2)
    response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
        Model: "gpt-6-astra",
        Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is deep research by OpenAI?")},
        Tools: []responses.ToolUnionParam{tool},
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(response)
}

来源示例31（java）

本段复用的中文释义：译释33。

// [中文] 将文件搜索结果上限设为2，以减少取回内容；较少结果可能影响回答质量。
// [中文] Java原例为API调用片段，需已有client及适用的外层类或方法；未作为独立Java文件编译。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.FileSearchTool;
import com.openai.models.responses.ResponseCreateParams;

String vectorStoreId = "<vector_store_id>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What is deep research by OpenAI?")
        .addTool(
            FileSearchTool.builder().addVectorStoreId(vectorStoreId).maxNumResults(2).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

来源示例32（csharp）

本段复用的中文释义：译释33。

// [中文] 将文件搜索结果上限设为2，以减少取回内容；较少结果可能影响回答质量。
using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
// [中文] 将占位ID替换为自己的向量存储ID。
// Replace this illustrative ID with your vector store ID.
string vectorStoreId = "<vector_store_id>";
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
    ResponseTool.CreateFileSearchTool([vectorStoreId], maxResultCount: 2)
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("What is deep research by OpenAI?")
);

ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

来源示例33（ruby）

本段复用的中文释义：译释33。

## [中文] 将文件搜索结果上限设为2，以减少取回内容；较少结果可能影响回答质量。
require "openai"

client = OpenAI::Client.new

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
    }
  ]
)

puts(response)

在响应中包含搜索结果

虽然输出文本的注解中可以看到文件引用，但文件搜索调用默认不会返回实际搜索结果。要在响应中包含搜索结果，在创建响应时传入 include 参数。

来源示例34（javascript）

本段复用的中文释义：译释33。

// [中文] include指定file_search_call.results，让响应携带实际检索结果；文件引用注解不等于结果正文。
const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: "What is deep research by OpenAI?",
  tools: [
    {
      type: "file_search",
      vector_store_ids: ["<vector_store_id>"],
    },
  ],
  // highlight-start
  // [中文] 请求在响应里附带文件搜索结果。
  include: ["file_search_call.results"],
  // highlight-end
});
console.log(response);

来源示例35（python）

本段复用的中文释义：译释33。

## [中文] include指定file_search_call.results，让响应携带实际检索结果；文件引用注解不等于结果正文。
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>"],
        }
    ],
    # highlight-start
    # [中文] 请求在响应里附带文件搜索结果。
    include=["file_search_call.results"],
    # highlight-end
)
print(response)

来源示例36（go）

本段复用的中文释义：译释33。

// [中文] include指定file_search_call.results，让响应携带实际检索结果；文件引用注解不等于结果正文。
package main

import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/responses"
)

func main() {
    client := openai.NewClient()
    response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
        Model:   "gpt-6-astra",
        Input:   responses.ResponseNewParamsInputUnion{OfString: openai.String("What is deep research by OpenAI?")},
        Tools:   []responses.ToolUnionParam{responses.ToolParamOfFileSearch([]string{"<vector_store_id>"})},
        Include: []responses.ResponseIncludable{responses.ResponseIncludableFileSearchCallResults},
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(response)
}

来源示例37（java）

本段复用的中文释义：译释33。

// [中文] include指定file_search_call.results，让响应携带实际检索结果；文件引用注解不等于结果正文。
// [中文] Java原例为API调用片段，需已有client及适用的外层类或方法；未作为独立Java文件编译。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseIncludable;
import java.util.List;

String vectorStoreId = "<vector_store_id>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What is deep research by OpenAI?")
        .addInclude(ResponseIncludable.of("file_search_call.results"))
        .addFileSearchTool(List.of(vectorStoreId))
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.fileSearchCall().stream())
    .flatMap(call -> call.results().stream())
    .flatMap(List::stream)
    .forEach(System.out::println);

来源示例38（csharp）

本段复用的中文释义：译释33。

// [中文] include指定file_search_call.results，让响应携带实际检索结果；文件引用注解不等于结果正文。
using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
// [中文] 将占位ID替换为自己的向量存储ID。
// Replace this illustrative ID with your vector store ID.
string vectorStoreId = "<vector_store_id>";
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(ResponseTool.CreateFileSearchTool([vectorStoreId]));
options.IncludedProperties.Add(IncludedResponseProperty.FileSearchCallResults);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("What is deep research by OpenAI?")
);

ResponseResult response = await client.CreateResponseAsync(options);
foreach (FileSearchCallResponseItem search in response.OutputItems.OfType<FileSearchCallResponseItem>())
{
    foreach (FileSearchCallResult result in search.Results)
    {
        Console.WriteLine($"{result.Filename}: {result.Text}");
    }
}

来源示例39（ruby）

本段复用的中文释义：译释33。

## [中文] include指定file_search_call.results，让响应携带实际检索结果；文件引用注解不等于结果正文。
require "openai"

client = OpenAI::Client.new

response = client.responses.create(
  model: "gpt-6-astra",
  input: "What is deep research by OpenAI?",
  # [中文] 请求在响应里附带文件搜索结果。
  include: ["file_search_call.results"],
  tools: [
    {
      type: :file_search,
      vector_store_ids: ["<vector_store_id>"]
    }
  ]
)

puts(response)

元数据过滤

可以根据文件的元数据筛选搜索结果。检索指南进一步介绍了：

如何为向量存储文件设置属性。
如何定义过滤条件。

来源示例40（javascript）

程序中的自然语言译释36：

博客（category属性值）。

程序中的自然语言译释37：

公告（category属性值）。

本段复用的中文释义：译释33。

// [中文] 使用in过滤器，只搜索category属性属于blog或announcement的文件；属性需要预先设置。
const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: "What is deep research by OpenAI?",
  tools: [
    {
      type: "file_search",
      vector_store_ids: ["<vector_store_id>"],
      // highlight-start
      filters: {
        // [中文] 按属性值集合进行成员匹配。
        type: "in",
        key: "category",
        value: ["blog", "announcement"],
      },
      // highlight-end
    },
  ],
});
console.log(response);

来源示例41（python）

本段复用的中文释义：译释33、译释36、译释37。

## [中文] 使用in过滤器，只搜索category属性属于blog或announcement的文件；属性需要预先设置。
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>"],
            # highlight-start
            "filters": {
                # [中文] 按属性值集合进行成员匹配。
                "type": "in",
                "key": "category",
                "value": ["blog", "announcement"],
            },
            # highlight-end
        }
    ],
)
print(response)

来源示例42（go）

本段复用的中文释义：译释33、译释36、译释37。

// [中文] 使用in过滤器，只搜索category属性属于blog或announcement的文件；属性需要预先设置。
package main

import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/responses"
    "github.com/openai/openai-go/v3/shared"
)

func main() {
    client := openai.NewClient()
    tool := responses.ToolParamOfFileSearch([]string{"<vector_store_id>"})
    tool.OfFileSearch.Filters = responses.FileSearchToolFiltersUnionParam{
        OfComparisonFilter: &shared.ComparisonFilterParam{
            Type: shared.ComparisonFilterTypeIn,
            Key:  "category",
            Value: shared.ComparisonFilterValueUnionParam{OfComparisonFilterValueArray: []shared.ComparisonFilterValueArrayItemUnionParam{
                {OfString: openai.String("blog")},
                {OfString: openai.String("announcement")},
            }},
        },
    }
    response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
        Model: "gpt-6-astra",
        Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is deep research by OpenAI?")},
        Tools: []responses.ToolUnionParam{tool},
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(response)
}

来源示例43（java）

本段复用的中文释义：译释33、译释36、译释37。

// [中文] 使用in过滤器，只搜索category属性属于blog或announcement的文件；属性需要预先设置。
// [中文] Java原例为API调用片段，需已有client及适用的外层类或方法；未作为独立Java文件编译。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ComparisonFilter;
import com.openai.models.responses.FileSearchTool;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;

String vectorStoreId = "<vector_store_id>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What is deep research by OpenAI?")
        .addTool(
            FileSearchTool.builder()
                .addVectorStoreId(vectorStoreId)
                .filters(
                    ComparisonFilter.builder()
                        .type(ComparisonFilter.Type.IN)
                        .key("category")
                        .valueOfComparisonFilterValueItems(
                            List.of(
                                ComparisonFilter.Value.ComparisonFilterValueItem.ofString(
                                    "blog"),
                                ComparisonFilter.Value.ComparisonFilterValueItem.ofString(
                                    "announcement")))
                        .build())
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

来源示例44（csharp）

本段复用的中文释义：译释33、译释36、译释37。

// [中文] 使用in过滤器，只搜索category属性属于blog或announcement的文件；属性需要预先设置。
using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
// [中文] 将占位ID替换为自己的向量存储ID。
// Replace this illustrative ID with your vector store ID.
string vectorStoreId = "<vector_store_id>";
ResponsesClient client = new(key);

BinaryData filters = BinaryData.FromString(
    """
    { "type": "in", "key": "category", "value": ["blog", "announcement"] }
    """
);
CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
    ResponseTool.CreateFileSearchTool([vectorStoreId], filters: filters)
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("What is deep research by OpenAI?")
);

ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

来源示例45（ruby）

本段复用的中文释义：译释33、译释36、译释37。

## [中文] 使用in过滤器，只搜索category属性属于blog或announcement的文件；属性需要预先设置。
require "openai"

client = OpenAI::Client.new

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"]
      }
    }
  ]
)

puts(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可用性	Responses：支持；Chat Completions：不支持；Assistants：原表标注支持，原参考入口现跳转至迁移说明。
速率限制	Build：500 RPM；Launch和Grow：1000 RPM。RPM指每分钟请求数。
费用与数据	内置工具定价；零数据保留（ZDR）与数据驻留。

以上保留官方文件搜索页面列示的图标关系与限制。2026年10月23日核验时，Assistants原参考入口已跳转至迁移说明，不能仅依据原表判断该API当前的生命周期或账户可用性；具体安排请结合对应迁移说明核对。

本章关联阅读：嵌入向量。