1. 为什么关键词搜索总找不到你要的东西你有没有过这种体验明明记得文档里写过「容器编排怎么选」搜「K8s 集群方案」却一条都出不来或者知识库里存着「iPhone 续航实测」你搜「苹果手机电池耐用吗」直接零结果。问题不在数据而在传统搜索的匹配方式——它只认字面不认意思。向量搜索引擎要解决的就是这件事。它把每段文本转成一串高维数字Embedding 向量语义相近的文本在向量空间里距离就近于是「苹果手机」和「iPhone」能自动靠拢「机器学习」和「深度学习」也能被判定为强相关。这套东西能做什么智能问答的知识召回、推荐系统的相似内容、企业文档的语义检索都是它的主战场。适合谁只要你会一点 Python、想让自己的项目「搜得懂人话」就够入门了。这篇我用 Claude Code 从零搭一个能跑通的向量搜索引擎覆盖文本向量化、语义匹配、相似检索三个环节并且把 Claude Code 接到 TaoToken 的统一 API 通道上省得你到处配 Key。全程本地可复现最后能打开一个网页搜索框输入自然语言就出结果。2. 前置准备把 Claude Code 接到 TaoToken 统一通道Claude Code 本身是个命令行里的 AI 编程助手你给它一句提示它帮你生成模块代码、跑测试、改 bug。但默认它要连官方通道配置麻烦、额度也散。我习惯用 TaoToken 做统一入口一个 Key 走通模型对话、编码、API 调用Claude Code 的配置里改一处就行。先拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进控制台在 API Keys 页面新建一个密钥复制备用。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 密钥管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。然后配置 Claude Code。它的配置文件通常在用户目录下的.claude/settings.json把 API 基址和 Key 指到 TaoToken{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这里ANTHROPIC_BASE_URL填https://taotoken.net/api注意不要带 UTM 参数这是给程序调用的干净地址。保存后重开终端运行claude进入交互随便问一句「你好」能正常回复说明通道通了。如果你更想先在网页里验证模型是否可用可以打开模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 试一句确认账号和额度没问题再回来配 Claude Code。注意Key 只存在本地配置文件里别提交到 Git。团队协作时用环境变量注入不要硬编码。3. 可复制配置让 Claude Code 生成搜索引擎骨架环境通了接下来让 Claude Code 干活。我在项目根目录建一个vector_search文件夹然后给 Claude Code 下第一条指令让它按分层结构生成代码。分层的好处是每层独立可替换——换 Embedding 模型不影响索引换索引不影响文档管理。先装依赖pip install sentence-transformers faiss-cpu numpy flask然后对 Claude Code 说请帮我创建一个向量搜索引擎项目结构如下 vector_search/ ├── embedder.py # 文本向量化模块 ├── vector_index.py # 基于 FAISS 的向量索引 ├── document_store.py # 文档管理与分块 ├── search_engine.py # 搜索核心整合以上三者 ├── web_app.py # Flask 搜索界面 └── main.py # 命令行入口 要求embedder 支持中英文、支持批量向量化和缓存 vector_index 支持余弦相似度和持久化 document_store 支持长文本自动分块 search_engine 提供统一 search 接口返回带相似度分数的结果。Claude Code 会依次生成这些文件。核心逻辑我挑重点说。embedder.py里用sentence-transformers加载多语言模型把文本编码成 384 维归一化向量余弦相似度直接等于点积省一次除法from sentence_transformers import SentenceTransformer import numpy as np class TextEmbedder: def __init__(self, model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2): self.model SentenceTransformer(model_name) self.dimension self.model.get_sentence_embedding_dimension() def embed(self, text): return self.model.encode(text, normalize_embeddingsTrue) def embed_batch(self, texts, batch_size64): return self.model.encode(texts, batch_sizebatch_size, normalize_embeddingsTrue, show_progress_barTrue) def similarity(self, t1, t2): v1, v2 self.embed(t1), self.embed(t2) return float(np.dot(v1, v2))vector_index.py用 FAISS 的IndexFlatIP做精确内积检索数据量大了可以切 IVF 或 HNSW。document_store.py负责把长文档按标点边界切成 512 字左右的块避免一句话被拦腰截断。search_engine.py把三者串起来add_documents批量入库search返回带分数的命中列表。4. 验证请求跑通语义匹配与相似检索代码生成完先做最小验证。写个测试脚本塞几条技术文档然后搜几个「字面不重合但意思相近」的查询看分数是否合理from search_engine import VectorSearchEngine engine VectorSearchEngine() docs [ 人工智能是计算机科学的重要分支致力于让机器具备类人智能, 深度学习是机器学习的一个子领域使用多层神经网络进行学习, Python 是最受欢迎的编程语言之一广泛用于数据科学和 AI 开发, Docker 是一个开源的容器化平台用于简化应用部署和管理, Kubernetes 是容器编排平台常与 Docker 配合使用, Vue.js 是一个渐进式 JavaScript 框架用于构建用户界面, React 是 Facebook 开发的前端框架采用组件化架构, ] engine.add_documents(docs, source技术知识库) resp engine.search(AI 和机器学习相关技术, top_k3) print(resp.summary())预期输出里「人工智能」和「深度学习」两条应该排最前相似度在 0.8 上下而「Docker」「Vue.js」这些不相关的会掉到 0.3 以下。再搜「前端开发框架」Vue 和 React 应该冒头。这就是语义匹配的价值——查询词和文档词没有一个字相同照样能命中。接着验证相似检索给定一篇文档找和它最像的其他文档。engine.similar_documents(doc_id0)会返回「人工智能」那条的邻居通常「深度学习」排第一。最后启动 Web 界面python main.py serve -p 5000浏览器打开http://localhost:5000输入「怎么部署应用」这类自然语言页面会列出 Docker、Kubernetes 相关条目并显示相似度百分比。到这一步文本向量化、语义匹配、相似检索的闭环就跑通了。5. 本篇常见错排查报错一ModuleNotFoundError: No module named faiss装的是faiss-cpu不是faiss导入名仍是faiss。如果 pip 装不上换conda install -c conda-forge faiss-cpu或者确认 Python 版本在 3.8 以上。报错二模型下载卡住或超时sentence-transformers首次运行要从远端拉模型权重。网络不稳时先手动下载模型目录再用本地路径初始化TextEmbedder(model_name/path/to/local-model)。别在循环里反复初始化模型加载一次复用即可。报错三搜索结果全是 0 分或分数异常多半是向量没归一化。余弦相似度要求向量单位化检查embed里有没有normalize_embeddingsTrueFAISS 侧有没有faiss.normalize_L2。两边都归一化后内积才等于余弦值。报错四IndexIVFFlat报「not trained」IVF 索引需要先训练聚类中心。数据量少于 100 条时直接退回IndexFlatIP或者先喂一批数据调index.train()。小数据量用 Flat 就够别过早优化。报错五Claude Code 连不上、返回鉴权错误回看settings.json里的ANTHROPIC_BASE_URL是不是https://taotoken.net/apiKey 有没有多余空格。改完配置要重开终端环境变量不会热加载。还不行就去接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照参数或者到 API Keys 页重新生成一个密钥试试。6. 继续往下走跑通最小闭环后你可以按需升级数据量上万条时把索引换成 HNSW检索延迟能从几十毫秒压到个位数文档分块加上重叠窗口召回更稳再往前一步把检索结果喂给大模型做 RAG 问答就是一套完整的智能知识库。如果你打算长期用 Claude Code 做这类编码项目建议开 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 额度更集中适合连续跑生成和调试。日常想快速验证某个模型效果模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 直接开聊就行。密钥和接入参数都在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 和 API Keys https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 里管理接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。下一篇我会用 Claude Code 生成 Docker 配置把今天这个搜索引擎一键容器化部署到时候直接docker compose up就能跑。
