baigle 小型搜索引擎第一阶段：用 Trae 自动编程打通 Whoosh + FastAPI 基本实现

1. baigle 第一阶段到底要跑通什么baigle 是一个参考公开搜索引擎思路做的小型搜索引擎项目第一阶段的目标不是做全站爬虫也不是接大模型而是把最小可用链路跑通用 Trae 自动编程生成 Whoosh 索引模块和 FastAPI 查询接口骨架实现「建索引 → 检索 → 返回结果」这条闭环。它适合正在学 Python 后端、想理解搜索引擎内部结构、又不想一上来就啃 Elasticsearch 的开发者。Whoosh 是纯 Python 实现的全文检索库不需要额外部署服务装完就能用FastAPI 负责把检索能力暴露成 HTTP 接口方便后面接前端或让程序调用。我这次的做法是先把项目骨架交给 Trae 生成再手工补齐配置和验证脚本。Trae 能快速产出目录结构和基础代码但索引字段、中文分词、返回结构这些细节必须自己盯否则很容易出现「索引建了但搜不到」的情况。下面按可复制的方式把 config.toml、settings.json、索引目录、启动命令和验证动作完整走一遍。你跟着做能在本地拿到一个能返回 JSON 结果的检索接口。2. 前置准备TaoToken 与 Trae 的配合方式Trae 自动编程在生成 Whoosh FastAPI 骨架时需要模型理解项目上下文。如果你用的是自带模型额度有限的版本或者想让生成结果更稳定可以先把模型调用通道配好。TaoToken 提供的是模型 API 接入能力地址是 https://taotoken.net/api 控制台在 https://taotoken.net/console API Key 在 https://taotoken.net/api-keys 生成。拿到 Key 之后在 Trae 的模型配置里填入自定义 API 地址和 Key就能让自动编程走这条通道。这一步不是必须的但如果你发现 Trae 生成代码时经常断、或者对 Whoosh 的 API 记不准换一个稳定的模型通道会明显改善。配置时注意API 地址填 https://taotoken.net/api 不要带多余路径Key 只填一次不要提交到 Git。模型对话入口在 https://taotoken.net/models 接入文档在 https://taotoken.net/doc 遇到 401 或 404 先查文档里的路径说明。3. 可复制配置config.toml 与 settings.json项目根目录建两个配置文件。config.toml 管索引路径和字段权重settings.json 管服务端口和索引目录。Trae 生成的骨架里通常会把配置写死在代码里我建议抽出来后面调参不用改 Python。# config.toml [index] index_dir ./data/index schema_fields [title, url, content, summary] [search] default_limit 10 max_limit 50 title_boost 2.0 content_boost 1.0 [crawler] max_depth 2 max_pages 10 timeout 10{ app: { host: 0.0.0.0, port: 8080, debug: true }, index: { dir: ./data/index, create_if_missing: true }, search: { default_limit: 10, snippet_length: 120 } }索引目录结构建议固定成下面这样Whoosh 会在 index_dir 下生成 _MAIN_xxx 等文件不要手动改baigle/ ├── app/ │ ├── main.py │ ├── search_engine.py │ └── models.py ├── config.toml ├── settings.json ├── data/ │ └── index/ │ ├── _MAIN_1.toc │ ├── _MAIN_1.seg │ └── ... └── scripts/ └── reset_and_test.pysearch_engine.py 里用 Whoosh 建 schema 时title 和 content 都要用 TEXT 并指定 analyzer中文场景下 Whoosh 自带的分词对中文不友好第一阶段可以先用空格切分或接 jieba。Trae 生成时容易漏掉 analyzer导致「爱因斯坦」搜不到这个坑后面排障会讲。4. 启动与验证建索引、检索、返回结果先装依赖pip install whoosh fastapi uvicorn pydantic requests beautifulsoup4启动 FastAPIuvicorn app.main:app --host 0.0.0.0 --port 8080 --reload服务起来后访问 http://localhost:8080/docs 能看到自动生成的接口文档。第一阶段至少要有两个接口POST /api/index 用于写入文档GET /api/search 用于检索。写入文档的请求体{ title: 爱因斯坦, url: http://example.com/einstein, content: 阿尔伯特·爱因斯坦是理论物理学家提出相对论。, summary: 爱因斯坦与相对论 }检索请求curl http://localhost:8080/api/search?q爱因斯坦limit5预期返回{ total: 1, results: [ { title: 爱因斯坦, url: http://example.com/einstein, summary: 爱因斯坦与相对论, score: 0.74 } ] }验证正确性时不要只看有没有返回要检查三件事total 是否等于实际写入条数、score 是否大于 0、title 是否命中查询词。如果 total 是 0说明索引没写进去或者查询字段不对如果 score 是 0说明 analyzer 没生效。我试过用 reset_and_test.py 先清索引再重新写入能排除旧数据干扰# scripts/reset_and_test.py from whoosh.index import create_in, open_dir from whoosh.fields import Schema, TEXT, ID import os INDEX_DIR ./data/index def reset_index(): if os.path.exists(INDEX_DIR): import shutil shutil.rmtree(INDEX_DIR) os.makedirs(INDEX_DIR) schema Schema( titleTEXT(storedTrue), urlID(storedTrue, uniqueTrue), contentTEXT(storedTrue), summaryTEXT(storedTrue) ) create_in(INDEX_DIR, schema) print(Index reset done.) if __name__ __main__: reset_index()跑完这个脚本再启动服务写入文档检索结果就能稳定复现。5. 本篇常见错排查第一个高频错误是 JSON decode error类似{detail:[{type:json_invalid,loc:[body,0]...}]}。这通常不是 FastAPI 的问题而是 curl 命令里的引号被 shell 吃掉了或者请求体不是合法 JSON。解决办法是把 JSON 写进文件再-d body.json或者用 Postman 发。另外注意 URL 里不要带未转义的花括号。第二个错误是搜不到中文。Whoosh 默认 StandardAnalyzer 按空格和标点切词中文整句会被当成一个 token。解决办法是在 schema 里给 TEXT 字段指定analyzerChineseAnalyzer()或者先用 jieba 分词再写入。如果暂时不想接 jieba至少把 content 按空格预处理。第三个错误是索引目录权限或路径不对。config.toml 里写的是相对路径./data/index但 uvicorn 启动目录不同会导致找不到。建议在代码里用Path(__file__).parent.parent拼绝对路径或者启动时打印当前索引目录确认。第四个错误是端口占用。8080 被占时 uvicorn 会报Address already in use换 8081 或先lsof -i:8080杀掉旧进程。如果服务起来了但 /docs 打不开检查是否开了 debug 和 CORS。6. 下一步把检索能力接进模型工作流第一阶段跑通后baigle 已经能返回结构化检索结果。接下来可以让程序把 query 发给检索接口拿到 title 和 summary 后拼进模型上下文这样模型在写代码或回答问题时就有外部网页信息参考。模型调用通道可以用 TaoToken 的 API地址 https://taotoken.net/api Key 在 https://taotoken.net/api-keys 生成接入文档在 https://taotoken.net/doc 。如果你要长期跑编码类 Agent可以看 Coding Planhttps://taotoken.net/coding-plan 。模型对话调试入口在 https://taotoken.net/models Claude Code 相关配置在 https://taotoken.net/claude-code 。先把 reset_and_test.py 跑通确认「爱因斯坦」能返回 score 大于 0 的结果再往下接模型。索引字段和 analyzer 定下来之后后面加爬虫、加缓存、加多字段权重都是在这个骨架上叠不会推翻重来。