File Search：从资料里找答案

11.1 今天你要完成什么

File Search 像一个会翻资料的助手。它应该优先根据你提供的文件回答，而不是随便编。

• 能解释 File Search 和普通聊天的区别。
• 能设计“只根据资料回答”的提示。
• 能在资料找不到答案时说不知道。
• 能把答案写成短句，方便学生阅读。

11.2 核心理论

理论不是背概念，而是帮你判断项目为什么这样设计。下面这些规则会在代码里反复出现。

• 核心理论：检索工具让模型先找资料再回答。Web Search 查网页，File Search 查你上传的文件。
• 来源理论：需要最新信息或资料依据的问题，答案必须带来源线索，否则不能当成可靠结论。
• 不知道理论：资料里没有答案时，好的系统应该说“没有找到”，而不是编一个看起来合理的答案。
• 输入契约：先规定用户要给什么资料。本课的输入要围绕“AI班级资料问答机器人”，不要让用户随便输入到程序无法处理。
• 输出契约：先规定 AI 必须交出什么结果。本课重点是“文件检索、资料依据、只回答资料中内容”，所以输出要能被人读懂，也要方便程序检查。
• 验证思维：AI 的一次好结果不等于项目可靠。至少用正常输入、边界输入、异常输入各测一次。
• 安全边界：API Key 是密码，不能写进浏览器前端，不能发截图，不能提交到公开仓库。

11.3 课堂讲解

这一课的项目是“AI班级资料问答机器人”，重点是“文件检索、资料依据、只回答资料中内容”。你可以把它当成一个小实验：先给它一个清楚输入，再观察代码里哪些地方用到了 File Search。课堂里我们不会一上来就追求复杂功能，而是先把最小版本做出来。最小版本跑通以后，你再改输入、改提示词、改输出格式，变化就会看得很清楚。

这几课让 AI 学会先查资料再回答。它不是只靠记忆说话，而是用网页或文件作为依据。

本课有一条很实用的学习线索：先问“用户到底给了什么”，再问“程序希望拿到什么”。比如你可以试这些输入：作业什么时候交？；请根据班级规则说迟交怎么办；资料里有没有提到项目评分标准？。这些输入故意有简单的，也有容易出问题的。正常输入能帮你确认功能；短输入、空输入、奇怪输入能帮你发现系统边界。

写代码时建议你分三轮。第一轮只跑通官方调用，不加自己的想法；第二轮把输入换成自己的例子，看看结果是否还合理；第三轮才开始改结构，比如增加字段、加错误提示、做网页交互。这个顺序有点慢，但很稳。真正浪费时间的不是慢，而是一下子改太多，最后不知道错在哪里。

资料里没有的内容，不要让 AI 编。说“没有找到”不是失败，而是诚实的系统行为。

理论部分要和代码一起看。比如“输入契约”不是一个漂亮词，它在代码里就是长度检查、必填字段、表单校验；“输出契约”也不是空话，它在代码里就是 JSON Schema、固定字段或页面渲染规则。你每写一行检查代码，都是在告诉系统：什么结果可以接受，什么结果需要退回去重新处理。

课堂里可以把同桌当成第一个用户。你把项目跑给同桌看，让对方换一个输入，观察系统会不会乱。很多问题都是别人随手一试才出现的，比如输入太短、问题太模糊、连续点击按钮、图片看不清。能处理这些小麻烦，作品就会从“我电脑上能跑”变成“别人也能用”。

最后做复盘时，不要只写“我学会了调用 API”。可以写得更具体：我学会了怎样限制输入，怎样让输出固定，怎样判断结果不可靠，怎样把报错变成用户看得懂的提示。这样的复盘有用，因为下一课你真的会再次用到它。

课堂讨论题

• 如果把“AI班级资料问答机器人”交给低年级学生使用，哪一步最容易让他们困惑？
• 这个项目里，哪些事情适合交给模型，哪些事情应该交给普通代码？
• 如果模型给出一个看起来不错但没有依据的答案，你打算怎样提醒用户？
• 你能不能把今天的项目换一个主题，但保持同样的输入、处理、输出结构？
• 如果只能保留一个测试用例，你会保留正常输入、边界输入还是异常输入？为什么？

11.4 先看例子

先把例子看懂，再动手写代码。你不需要一次记住所有概念，先能说清楚“输入是什么、输出是什么、程序要检查什么”。

你可以替换成这些输入

• 作业什么时候交？
• 请根据班级规则说迟交怎么办。
• 资料里有没有提到项目评分标准？
• 老师的微信是什么？
• 这份讲义里如何解释变量？

11.5 完整代码实现

下面同时给出 Node.js 和 Python 两套完整最小实现。先任选一种原样跑通，再改输入、改提示词、改输出格式。

Node.js 运行方式

1. 新建文件 lesson-11.mjs，把下面完整代码放进去。
2. 在终端运行：npm init -y
3. 安装依赖：npm install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：node lesson-11.mjs
6. 再新建一个 class_rules.txt，写入几条班级规则。

Node.js 完整代码

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI();
const MODEL = process.env.OPENAI_MODEL || "gpt-5.5";

const filePath = "class_rules.txt";

if (!fs.existsSync(filePath)) {
  fs.writeFileSync(
    filePath,
    [
      "班级规则",
      "1. 作业需要在每周日晚上 8 点前提交。",
      "2. 如果作业迟交，需要在下节课前补交。",
      "3. 项目展示需要说明：目标、输入、输出、测试记录。",
      "4. API Key 不能写进前端代码，也不能发截图。",
    ].join("\n"),
    "utf8"
  );
}

const uploadedFile = await client.files.create({
  file: fs.createReadStream(filePath),
  purpose: "assistants",
});

const vectorStore = await client.vectorStores.create({
  name: "class_rules_knowledge_base",
});

await client.vectorStores.files.create(vectorStore.id, {
  file_id: uploadedFile.id,
});

async function waitForVectorStoreReady(vectorStoreId) {
  for (let i = 0; i < 20; i++) {
    const files = await client.vectorStores.files.list({
      vector_store_id: vectorStoreId,
    });
    const statuses = files.data.map((file) => file.status);
    if (statuses.length > 0 && statuses.every((status) => status === "completed")) {
      return;
    }
    if (statuses.some((status) => status === "failed")) {
      throw new Error("文件处理失败，请检查文件格式。");
    }
    await new Promise((resolve) => setTimeout(resolve, 1000));
  }
  throw new Error("文件处理超时，请稍后重试。");
}

await waitForVectorStoreReady(vectorStore.id);

const response = await client.responses.create({
  model: MODEL,
  input: "作业什么时候交？如果资料里没有答案，请直接说没有找到。",
  tools: [
    {
      type: "file_search",
      vector_store_ids: [vectorStore.id],
    },
  ],
});

console.log(response.output_text);

Python 运行方式

1. 新建文件 lesson-11.py，把下面完整代码放进去。
2. 建议新建虚拟环境后再安装依赖。
3. 安装依赖：pip install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：python lesson-11.py
6. 代码会自动创建 class_rules.txt，也可以自己改成课堂资料。

Python 完整代码

from openai import OpenAI
from pathlib import Path
import os
import time

client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")

file_path = Path("class_rules.txt")

if not file_path.exists():
    file_path.write_text(
        "\n".join([
            "班级规则",
            "1. 作业需要在每周日晚上 8 点前提交。",
            "2. 如果作业迟交，需要在下节课前补交。",
            "3. 项目展示需要说明：目标、输入、输出、测试记录。",
            "4. API Key 不能写进前端代码，也不能发截图。",
        ]),
        encoding="utf-8",
    )

with file_path.open("rb") as f:
    uploaded_file = client.files.create(file=f, purpose="assistants")

vector_store = client.vector_stores.create(name="class_rules_knowledge_base")

client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=uploaded_file.id,
)


def wait_for_vector_store_ready(vector_store_id):
    for _ in range(20):
        files = client.vector_stores.files.list(vector_store_id=vector_store_id)
        statuses = [item.status for item in files.data]
        if statuses and all(status == "completed" for status in statuses):
            return
        if any(status == "failed" for status in statuses):
            raise RuntimeError("文件处理失败，请检查文件格式。")
        time.sleep(1)
    raise RuntimeError("文件处理超时，请稍后重试。")


wait_for_vector_store_ready(vector_store.id)

response = client.responses.create(
    model=MODEL,
    input="作业什么时候交？如果资料里没有答案，请直接说没有找到。",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": [vector_store.id],
        }
    ],
)

print(response.output_text)

11.6 跟着做

1. 准备一份短资料，例如班级规则。
2. 让 AI 先检索资料，再回答。
3. 提示词中写明：资料没有就说没有找到。
4. 测试一个资料中有答案的问题。
5. 再测试一个资料中没有答案的问题。

11.7 常见错误

• 资料里没有答案，AI 却自己补充。
• 上传资料太乱，没有标题和结构。
• 问题太模糊，检索不到重点。
• 没有告诉用户答案来自资料。

11.8 课后练习

1. 用一页自己的学习笔记做问答机器人。
2. 准备 3 个能答的问题和 1 个不能答的问题。
3. 不能答时输出：资料中没有找到。

11.9 自测清单

• 我的回答有没有依据资料？
• 资料没有时会不会承认不知道？
• 我的资料是否清楚分段？
• 答案是否短而准确？