限制条数、带回检索片段与 metadata 过滤

本课目标

在第 1 课已能提问的基础上：

1. 用 max_num_results 控制检索条数（降延迟 / token）
2. 用 include=["file_search_call.results"] 把检索片段本身带回响应（默认只有 citation，没有 chunk 正文）
3. 用 filters 按文件 metadata 过滤
4. 对照官方支持的文件格式表，避免上传不支持类型

步骤 1：限制检索条数

from openai import OpenAI

client = OpenAI()
vector_store_id = "vs_..."

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

对照结果：调用成功；官方说明减少条数可降低 token 与延迟，但可能降低答案完整度。可把 2 改成 5 对比回答长度与 citation 数量。

步骤 2：把检索片段写进响应

默认：你能在 output_text.annotations 里看到 file_citation，但 file_search_call.search_results 常为 null。要调试「到底搜到了哪几段」，加上 include：

from openai import OpenAI

client = OpenAI()
vector_store_id = "vs_..."

response = client.responses.create(
    model="gpt-4.1-mini",
    input="What is deep research by OpenAI?",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": [vector_store_id],
        }
    ],
    include=["file_search_call.results"],
)

for item in response.output:
    if getattr(item, "type", None) == "file_search_call":
        print("queries:", getattr(item, "queries", None))
        print("results:", getattr(item, "results", None) or getattr(item, "search_results", None))

对照结果：file_search_call 上应能看到具体检索结果片段（字段名以你 SDK 序列化为准，常见为 results / 含 filename、文本片段与分数）。这是排查「答非所问」时最有用的开关。

步骤 3：按 metadata 过滤

若你在向量库文件上设置了属性（做法见 Retrieval），可在工具参数里加 filters。官方示例：

from openai import OpenAI

client = OpenAI()
vector_store_id = "vs_..."

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

对照结果：

• 若文件没有对应 metadata：过滤可能让检索为空，回答会缺少 citation——这是预期现象，先给文件写上 category 再试。
• 若已写入且命中：行为与第 1 课类似，但只在过滤后的子集里搜。

步骤 4：对照官方支持的文件类型

text/ MIME 的编码须为 utf-8、utf-16 或 ascii。常用格式（摘自官方表，完整表以文档页为准）：

上传不在表内的类型时，索引可能 failed——换格式或拆成 .txt / .md 再挂库。

步骤 5：用量与收尾建议

官方 Usage notes（以文档页当前表为准）：File Search 可用于 Responses（以及文档列出的其他 API 面），并有按 Tier 的 RPM 限制；计费与数据驻留说明见文档页「Pricing / ZDR」链接。

实战收尾建议：

1. 开发时打开 include=["file_search_call.results"]，上线可关掉以省响应体积。
2. 先用小 max_num_results 压延迟，再按答案质量往上调。
3. 多租户 / 多产品线用 metadata + filters 隔离语料，避免串库。
4. 清理测试资源：不用的 vs_... / file-... 在 Dashboard 或 API 中删除，避免残留计费与配额占用。

到这里，你已经跑通官方托管 RAG 主路径，并能调检索条数、查看 chunk、按属性过滤。需要更深的分块 / 嵌入原理时，继续读 Retrieval。