文件搜索

文件搜索是一个助手工具，它可以使用 OpenAI 的模型以外的知识，例如专有产品信息或用户提供的文档，来回答用户的问题。OpenAI 会自动解析和切分您的文档，创建和存储嵌入式，并使用向量和关键字搜索来检索相关内容，以回答用户的查询。

快速入门

在本示例中，我们将创建一个助手，以帮助回答有关公司财务报表的问题。

步骤 1：创建一个新的助手，并启用文件搜索

创建一个新的助手，并在助手的 tools 参数中启用 file_search。

from openai import OpenAI

client = OpenAI()

assistant = client.beta.assistants.create(
    name="财务分析师助手",
    instructions="你是一名专业的财务分析师。利用你的知识库来回答有关经审计的财务报表的问题。",
    model="gpt-4o",
    tools=[{"type": "file_search"}],
)

一旦启用了 file_search 工具，模型将在基于用户消息的上下文中决定是否检索内容。

步骤 2：上传文件并将其添加到向量存储中

为了让助手访问您的文件，file_search 工具使用向量存储对象。向量存储对象是一个可搜索的数据结构，它将文本文档的嵌入式表示与文档本身关联。

要将文件添加到向量存储中，请执行以下步骤：

创建一个新的向量存储对象。
上传要添加到向量存储中的文件。
将文件添加到向量存储中。
轮询向量存储的状态，直到所有文件都处于 completed 状态。

vector_store = client.beta.vector_stores.create(name="Financial Statements")

file_paths = ["edgar/goog-10k.pdf", "edgar/brka-10k.txt"]
file_streams = [open(path, "rb") for path in file_paths]

file_batch = client.beta.vector_stores.file_batches.upload_and_poll(
    vector_store_id=vector_store.id, files=file_streams
)

print(file_batch.status)
print(file_batch.file_counts)

步骤 3：更新助手以使用新的向量存储

为了使新的向量存储对您的助手可用，请更新助手的 tool_resources 以包含新的向量存储 ID。

assistant = client.beta.assistants.update(
    assistant_id=assistant.id,
    tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},
)

步骤 4：创建一个线程

您还可以将文件作为消息附件在您的线程中附加。这将在您的线程中创建一个新的向量存储，或者如果该线程已经有一个向量存储，则将新文件添加到现有的线程向量存储中。当您在该线程上创建一个运行时，file_search 工具将查询助手的向量存储和线程的向量存储。

在本示例中，用户附加了 Apple 的最新 10-K 申报。

message_file = client.files.create(
    file=open("edgar/aapl-10k.pdf", "rb"), purpose="assistants"
)

thread = client.beta.threads.create(
    messages=[
        {
            "role": "user",
            "content": "2023 年 10 月底 AAPL 的流通股数有多少？",
            "attachments": [
                {
                    "file_id": message_file.id,
                    "tools": [{"type": "file_search"}],
                }
            ],
        }
    ]
)

print(thread.tool_resources.file_search)

向量存储对象的大小是所有解析的文档块和其对应的嵌入式表示的总和。您的第一个 GB 是免费的，超过该数量后，按每 GB 每天 0.10 美元的费用收取向量存储的使用情况。没有其他的费用。

为了帮助您管理与这些向量存储对象相关的成本，我们在向量存储对象中添加了过期策略的支持。您可以在创建或更新向量存储对象时设置这些策略。

vector_store = client.beta.vector_stores.create_and_poll(
    name="Product Documentation",
    file_ids=["file_1", "file_2", "file_3", "file_4", "file_5"],
    expires_after={
        "anchor": "last_active_at",
        "days": 7,
    },
)

线程向量存储具有默认的过期策略

在线程中使用助手创建的向量存储具有默认的过期策略，即在向量存储最后一次活动（定义为向量存储是运行的一部分）后的 7 天。

当向量存储过期时，在该线程上的运行将失败。要解决此问题，您可以简单地使用相同的文件创建一个新的向量存储，并将其重新附加到线程。

all_files = list(client.beta.vector_stores.files.list("vs_expired"))

vector_store = client.beta.vector_stores.create(name="rag-store")

client.beta.threads.update(
    "thread_abc123",
    tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},
)

for file_batch in chunked(all_files, 100):
    client.beta.vector_stores.file_batches.create_and_poll(
        vector_store_id=vector_store.id, file_ids=[file.id for file in file_batch]
    )

如何运作

file_search 工具在助手的运行期间执行以下操作：

它会监听用户的查询，并在需要时触发。
它会将用户的查询重写为一个或多个搜索查询。
它会在向量存储和关键字索引中执行搜索查询。
它会对检索到的文档进行排名，并选择前几个文档。
它会将所选文档的内容添加到助手的上下文中。
它会在助手生成的响应中添加对所选文档的引用。

file_search 工具的默认配置如下：

切分大小：800 个令牌
切分重叠：400 个令牌
嵌入模型： text-embedding-3-large ，维数为 256
最大上下文文档数：20 个（可能少于此数）

向量存储

向量存储对象是一个可搜索的数据结构，它将文本文档的嵌入式表示与文档本身关联。向量存储对象可以包含多达 10,000 个文件。向量存储对象可以附加到助手和线程。目前，您最多可以将一个向量存储对象附加到助手，并最多将一个向量存储对象附加到线程。

创建向量存储对象并添加文件

您可以在单个 API 调用中创建向量存储对象并将文件添加到其中：

vector_store = client.beta.vector_stores.create(
    name="Product Documentation",
    file_ids=["file_1", "file_2", "file_3", "file_4", "file_5"],
)

将文件添加到向量存储对象是一个异步操作。为了确保该操作已完成，我们建议您使用我们的官方 SDK 中的 '创建和轮询' 帮助程序。如果您未使用 SDK，则可以检索向量存储对象并监视其 file_counts 属性，以查看文件引入操作的结果。

文件也可以在向量存储对象创建后将其添加到向量存储对象中，方法是创建向量存储文件：

file = client.beta.vector_stores.files.create_and_poll(
    vector_store_id="vs_abc123",
    file_id="file-abc123",
)

或者，您可以将多达 500 个文件添加到向量存储对象中，方法是创建批次：

batch = client.beta.vector_stores.file_batches.create_and_poll(
    vector_store_id="vs_abc123",
    file_ids=["file_1", "file_2", "file_3", "file_4", "file_5"],
)

类似地，这些文件可以通过删除向量存储文件对象或者通过删除底层文件对象（这将从您的组织中的所有助手和线程配置中删除该文件）从向量存储对象中删除。

最大文件大小为 512 MB。每个文件最多包含 5,000,000 个令牌（在将文件附加时自动计算）。

File Search 支持各种文件格式，包括 .pdf， .md 和 .docx。有关支持的文件扩展名（及其对应的 MIME 类型）的更多详细信息，请参阅支持的文件一节。

附加向量存储对象

您可以将向量存储对象附加到助手或线程，方法是使用 tool_resources 参数。

assistant = client.beta.assistants.create(
    instructions="你是一个有用的产品支持助手，你会根据提供给你的文件来回答问题。",
    model="gpt-4o",
    tools=[{"type": "file_search"}],
    tool_resources={
        "file_search": {
            "vector_store_ids": ["vs_1"],
        }
    },
)

thread = client.beta.threads.create(
    messages=[{"role": "user", "content": "如何取消我的订阅？"}],
    tool_resources={
        "file_search": {
            "vector_store_ids": ["vs_2"],
        }
    },
)

您也可以在创建助手或线程之后将向量存储对象附加到其中，方法是使用正确的 tool_resources 更新它们。

在将向量存储对象附加到助手或线程之前，我们强烈建议您确保所有文件都已完成处理。这将确保向量存储对象中的所有数据都是可搜索的。您可以使用 SDK 中的轮询帮助程序来检查向量存储对象的就绪状态，或者手动轮询向量存储对象以确保其 status 为 completed。

作为后备，我们在运行对象中建立了最长 60 秒的等待时间，以确保线程的向量存储对象中的文件已完成处理。这个后备等待时间不适用于助手的向量存储对象。

管理成本