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

检索

根据语义相似度搜索您的数据。

通过检索 API,您可以对自己的数据执行语义搜索。即使结果与查询只有少量关键词匹配,甚至没有任何关键词匹配,语义搜索也能找到含义相近的内容。您可以单独使用检索功能,也可以结合我们的模型,根据检索结果生成回答,进一步发挥检索的作用。

检索流程示意图

检索 API 使用向量存储为您的数据建立索引。本指南将介绍如何执行语义搜索,并详细说明向量存储的使用方法。

快速入门

  • 创建向量存储并上传文件。

  • 创建向量存储并添加文件
    from openai import OpenAI
    
    client = OpenAI()
    
    vector_store = client.vector_stores.create(        # Create vector store
        name="Support FAQ",
    )
    
    client.vector_stores.files.upload_and_poll(        # Upload file
        vector_store_id=vector_store.id,
        file=open("customer_policies.txt", "rb")
    )
  • 发送搜索查询以获取相关结果。

  • 搜索查询
    user_query = "What is the return policy?"
    
    results = client.vector_stores.search(
        vector_store_id=vector_store.id,
        query=user_query,
    )

    如需了解如何让我们的模型利用搜索结果,请参阅根据搜索结果生成回答。

    语义搜索

    语义搜索利用向量嵌入查找语义相关的结果。即使结果与查询只有少量共同关键词,甚至完全没有共同关键词,语义搜索也能找到这些传统搜索方法可能遗漏的结果。

    例如,英文查询 "When did we go to the moon?"(我们是什么时候登上月球的?)可能得到以下结果:

    文本 关键词相似度 语义相似度
    The first lunar landing occurred in July of 1969.(人类于 1969 年 7 月首次登月。) 0% 65%
    The first man on the moon was Neil Armstrong.(第一个踏上月球的人是 Neil Armstrong。) 27% 43%
    When I ate the moon cake, it was delicious.(我吃月饼的时候,觉得它很好吃。) 40% 28%

    (关键词相似度按交并比计算。语义相似度按余弦相似度计算,使用的嵌入模型为 text-embedding-3-small。)

    在这个例子中,相关性最高的结果在英文原文中没有用到查询中的任何单词。凭借这种灵活性,语义搜索可以有效查询各种规模的知识库。

    语义搜索依赖向量存储,本指南稍后会详细介绍。本节重点介绍如何执行和调整语义搜索。

    执行语义搜索

    您可以调用 search 函数,并用自然语言指定 query 来查询向量存储。函数会返回结果列表,每条结果都包含相关文本块、相似度得分和来源文件。

    搜索查询
    results = client.vector_stores.search(
        vector_store_id=vector_store.id,
        query="How many woodchucks are allowed per passenger?",
    )
    搜索结果
    {
      "object": "vector_store.search_results.page",
      "search_query": "How many woodchucks are allowed per passenger?",
      "data": [
        {
          "file_id": "file-12345",
          "filename": "woodchuck_policy.txt",
          "score": 0.85,
          "attributes": {
            "region": "North America",
            "author": "Wildlife Department"
          },
          "content": [
            {
              "type": "text",
              "text": "According to the latest regulations, each passenger is allowed to carry up to two woodchucks."
            },
            {
              "type": "text",
              "text": "Ensure that the woodchucks are properly contained during transport."
            }
          ]
        },
        {
          "file_id": "file-67890",
          "filename": "transport_guidelines.txt",
          "score": 0.75,
          "attributes": {
            "region": "North America",
            "author": "Transport Authority"
          },
          "content": [
            {
              "type": "text",
              "text": "Passengers must adhere to the guidelines set forth by the Transport Authority regarding the transport of woodchucks."
            }
          ]
        }
      ],
      "has_more": false,
      "next_page": null
    }

    默认情况下,每次响应最多包含 10 条结果。您可以通过 max_num_results 参数调整上限,最高可设为 50 条。

    查询改写

    某些查询方式能得到更好的结果。您可以启用自动改写,让系统优化查询。将 rewrite_query=true 作为参数传给 search 即可启用此功能。

    您可以在结果的 search_query 字段中查看改写后的查询。

    原始查询 改写后的查询
    我想知道主办公楼有多高。 主办公楼高度
    运输危险品需要遵守哪些安全规定? 危险品安全规定
    我该如何就服务问题提出投诉? 服务投诉流程

    按属性筛选

    您可以设置筛选条件来缩小结果范围,例如只搜索特定日期范围内的文件。在执行语义搜索之前,您可以在 filters 中定义并组合条件,按属性筛选要搜索的文件。

    使用比较筛选器,可以指定一个 key,将该键在文件的 attributes 中对应的值与给定的 value 进行比较。使用复合筛选器,可以通过 and 和 or 组合多个筛选器。

    比较筛选器
    {
      "type": "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin",  // comparison operators
      "key": "attributes_key",                           // attributes key
      "value": "target_value"                             // value to compare against
    }
    复合筛选器
    {
      "type": "and" | "or",                                // logical operators
      "filters": [...]
    }

    以下是一些筛选器示例。

    下面按文件名筛选的示例匹配的是自定义 filename 属性。您必须为向量存储中的每个文件显式设置该属性,例如 {"filename": "example.txt"}。这些筛选器不会自动匹配上传文件的名称。

    按地区筛选
    {
      "type": "eq",
      "key": "region",
      "value": "us"
    }

    结果排序

    如果文件搜索结果的相关性不够高,您可以调整 ranking_options 来改善返回结果的质量。您可以指定 ranker,例如 auto 或 default-2024-08-21,并将 score_threshold 设为 0.0 到 1.0 之间的值。提高 score_threshold 可以只保留相关性更高的文本块,但也可能排除一些有用的内容。如果设置了 ranking_options.hybrid_search,您还可以调整 hybrid_search.embedding_weight(rrf_embedding_weight)和 hybrid_search.text_weight(rrf_text_weight),控制倒数排名融合算法如何权衡语义嵌入匹配与稀疏关键词匹配。提高前者的权重会更看重语义相似度,提高后者的权重会更看重文本重合度。请确保至少有一个权重大于零。

    向量存储

    向量存储是保存可搜索文件的容器,为检索 API 和文件搜索工具提供语义搜索功能。将文件添加到向量存储后,系统会自动将文件分块、生成嵌入并建立索引。

    向量存储包含 vector_store_file 对象,每个对象都关联一个底层 file 对象。

    对象类型
    说明
    file 表示通过文件 API 上传的内容。通常与向量存储配合使用,也可用于微调等场景。
    vector_store 用于存放可搜索文件的容器。
    vector_store.file 封装 file 的类型,表示该文件已分块、已生成嵌入,并已关联到一个 vector_store。
    包含用于筛选的 attributes 映射。

    定价

    费用按所有向量存储占用的总空间计算。占用空间取决于解析得到的文本块及其对应嵌入的大小。

    存储用量 费用
    1 GB 以内(所有向量存储合计) 免费
    超出 1 GB 的部分 每 GB 每天 0.10 美元

    如需了解如何尽量降低费用,请参阅过期策略。

    向量存储操作

    创建向量存储
    client.vector_stores.create(
        name="Support FAQ",
        file_ids=["file_123"]
    )

    向量存储文件操作

    某些操作是异步的,可能需要一段时间才能完成。例如,create 用于创建 vector_store.file 对象,您可以使用 create_and_poll 等辅助函数阻塞等待,直到操作完成。您也可以自行查询操作状态。从向量存储移除文件采用最终一致性机制,因此移除文件后的一小段时间内,搜索结果仍可能包含该文件的内容。

    添加文件的请求按向量存储 ID 实施速率限制。对于同一个向量存储,发往 /vector_stores/{vector_store_id}/files 和 /vector_stores/{vector_store_id}/file_batches 的请求共用每分钟 300 次的限额。

    创建向量存储文件
    client.vector_stores.files.create_and_poll(
        vector_store_id="vs_123",
        file_id="file_123"
    )

    批处理操作

    创建文件批次
    client.vector_stores.file_batches.create_and_poll(
        vector_store_id="vs_123",
        files=[
            {
                "file_id": "file_123",
                "attributes": {"department": "finance"}
            },
            {
                "file_id": "file_456",
                "chunking_strategy": {
                    "type": "static",
                    "static": {
                        "max_chunk_size_tokens": 1200,
                        "chunk_overlap_tokens": 200
                    }
                }
            }
        ]
    )

    创建批次时,您可以提供 file_ids,并按需设置 attributes、chunking_strategy 或两者。您也可以通过 files 数组为每个文件传入一个对象,其中必须包含 file_id,还可按需设置 attributes 和 chunking_strategy。两种方式只能选其一:前者让所有文件共用相同设置,后者允许逐个文件覆盖设置。

    如果您希望提高向单个向量存储导入文件的吞吐量,建议尽可能采用批量创建。一次批量请求最多可包含 500 个文件。与发送大量单文件创建请求相比,批量创建通常能减少资源争用,降低端到端延迟。

    属性

    每个 vector_store.file 都可以关联一个 attributes 字典。执行语义搜索时,您可以通过按属性筛选来引用字典中的值。字典最多可包含 16 个键。每个键最长为 64 个字符,每个字符串值最长为 512 个字符。

    创建带属性的向量存储文件
    client.vector_stores.files.create(
        vector_store_id="<vector_store_id>",
        file_id="file_123",
        attributes={
            "region": "US",
            "category": "Marketing",
            "date": 1672531200      # Jan 1, 2023
        }
    )

    过期策略

    您可以为 vector_store 对象设置 expires_after 来指定过期策略。向量存储过期后,系统会删除所有关联的 vector_store.file 对象,并停止对这些对象计费。

    设置向量存储的过期策略
    client.vector_stores.update(
        vector_store_id="vs_123",
        expires_after={
            "anchor": "last_active_at",
            "days": 7
        }
    )

    限制

    单个文件最大为 512 MB。每个文件包含的 Token 数不应超过 5,000,000。添加文件时,系统会自动计算 Token 数。

    分块

    默认情况下,max_chunk_size_tokens 为 800,chunk_overlap_tokens 为 400。这意味着系统会按每块 800 个 Token 拆分文件并建立索引,相邻文本块之间有 400 个 Token 重叠。

    将文件添加到向量存储时,您可以设置 chunking_strategy 来调整分块方式。分块策略有以下限制:

    • max_chunk_size_tokens 必须在 100 到 4096 之间(含两端)。
    • chunk_overlap_tokens 必须为非负数,且不应超过 max_chunk_size_tokens / 2。

    根据搜索结果生成回答

    执行查询后,如果您想根据结果生成回答,可以将搜索结果和原始查询一并提供给我们的模型,让模型给出有据可依的回答。

    执行搜索查询以获取结果
    from openai import OpenAI
    
    client = OpenAI()
    
    user_query = "What is the return policy?"
    
    results = client.vector_stores.search(
        vector_store_id=vector_store.id,
        query=user_query,
    )
    根据搜索结果生成回答
    # Use results and user_query from the preceding search step.
    formatted_results = format_results(results.data)
    
    "\n".join("\n".join(c.text for c in result.content) for result in results.data)
    
    completion = client.chat.completions.create(
        model="gpt-6.2-astra",
        messages=[
            {
                "role": "developer",
                "content": "Produce a concise answer to the query based on the provided sources.",
            },
            {
                "role": "user",
                "content": f"Sources: {formatted_results}\n\nQuery: '{user_query}'",
            },
        ],
    )
    
    print(completion.choices[0].message.content)
    "Our return policy allows returns within 30 days of purchase."

    此示例使用 format_results 函数来格式化结果。该函数的一种实现如下:

    结果格式化函数示例
    def format_results(results):
        formatted_results = ""
        for result in results.data:
            formatted_result = (
                f"<result file_id='{result.file_id}' file_name='{result.filename}'>"
            )
            for part in result.content:
                formatted_result += f"<content>{part.text}</content>"
            formatted_results += formatted_result + "</result>"
        return f"<sources>{formatted_results}</sources>"