企业官网建设流程全解析

1. 项目概述：本地化语义搜索引擎的实战落地逻辑

我做过不下二十个基于大模型的文档处理项目，从给律所做合同条款比对，到帮医疗器械公司解析FDA申报材料，再到给高校图书馆建古籍检索系统。所有这些项目的起点，几乎都绕不开一个最朴素的问题：怎么让机器“读懂”PDF里那些密密麻麻的文字？不是简单地Ctrl+F找关键词，而是能理解“股东信里提到的‘长期主义’和年报中‘资本配置’其实是同一战略逻辑的不同表述”——这才是语义搜索要解决的核心痛点。

这个项目标题里的“Semantic Search Engine Using Langchain”，说白了就是用LangChain这套工具链，在你自己的电脑上搭一个不依赖云端API、不上传任何敏感数据、能真正理解文档语义的本地搜索引擎。它不追求炫技，也不堆砌模型参数，而是聚焦在“把一份PDF扔进去，输入一句自然语言提问，比如‘亚马逊2023年在物流基础设施上的投入重点是什么？’，就能精准定位到原文段落并给出依据”。关键词里反复出现的“Towards AI - Medium”，其实暗示了它的原始场景：一篇面向工程师的实操笔记，不是学术论文，也不是产品白皮书，而是作者在调试过程中随手记下的关键步骤、踩过的坑、以及为什么选A不选B的真实思考。

它适合三类人：第一类是刚接触RAG（检索增强生成）概念的开发者，想甩开教程视频，直接拿一个最小可行代码跑通全流程；第二类是企业内负责知识管理的技术人员，需要快速验证本地化部署的可行性，评估是否值得投入资源做定制开发；第三类是注重数据隐私的业务方，比如金融、医疗行业的从业者，他们宁可多花两小时配环境，也不愿把客户财报或病历PDF上传到任何第三方服务。这个项目的价值，不在于它有多前沿，而在于它把一套原本分散在十几篇文档里的技术拼图，用最直白的方式焊在了一起——从PDF解析、文本切片、向量嵌入，到相似度检索，每一步都经得起拷问，也经得起你在自己电脑上敲下node index.js后看到的第一行8（代表成功加载了8页PDF）时，那种真实的、不掺水的确定感。

2. 整体架构设计与核心组件选型逻辑

2.1 为什么是LangChain？而不是手写Embedding Pipeline？

很多人一上来就想“既然核心是向量化，那我直接调OpenAI API，再用FAISS存向量不就行了？”——这思路没错，但漏掉了工程落地中最耗神的“胶水层”。LangChain不是万能的，但它解决了一个非常具体、非常痛的问题：如何把不同来源的非结构化数据（PDF、Word、网页、数据库）统一成一种标准格式，并无缝接入下游的向量存储与检索流程？它的Document对象，就是这个统一接口。你看原始代码里loader.load()返回的docs数组，每个元素都是一个结构清晰的{ pageContent, metadata }对象。这个metadata里不仅有文件路径，还有pdf: { totalPages: 8 }这种元信息。这意味着，当你后续做检索时，不仅能返回匹配的文本片段，还能立刻知道“这段话来自PDF的第几页”，这对审计、法务等强溯源需求的场景，是刚需，不是锦上添花。

提示：LangChain的@langchain/community包，本质是一个“适配器市场”。它不生产Embedding模型，也不维护向量数据库，而是提供标准化的Loader（加载器）、TextSplitter（切片器）、Embeddings（嵌入器）、VectorStore（向量库）接口。你今天用PDFLoader，明天换成DocxLoader，只要它们都遵循同一个DocumentLoader接口，上层的检索逻辑一行代码都不用改。这种解耦，是项目能快速迭代、横向扩展的基础。

2.2 PDF解析为何选pdf-parse而非pdf-lib或poppler？

原始代码里npm i pdf-parse这行命令，背后有明确的取舍逻辑。pdf-parse是一个纯JavaScript实现的PDF解析库，它的核心优势是零依赖、跨平台、开箱即用。你不需要在Mac上装Homebrew，在Windows上配Visual Studio Build Tools，在Linux上编译C++依赖——pdf-parse直接通过Node.js的Buffer就能读取PDF二进制流，然后用JS解析其内部的文本流结构。

对比一下其他选项：

• pdf-lib：功能强大，擅长PDF编辑（增删页、加水印），但不擅长文本提取。它更像一个PDF的“画布”，你要自己去遍历每一页的字体、坐标、文本块，再拼接成可读文字，工作量巨大且容易出错。
• poppler（通过pdfjs-dist或node-poppler调用）：这是业界公认的高精度PDF解析方案，尤其对扫描版PDF（OCR后）支持极好。但它需要系统级安装，apt-get install poppler-utils或brew install poppler，一旦CI/CD流水线换环境，就可能卡壳。

注意：pdf-parse的短板也很明显——它对扫描版PDF完全无效。它只能处理原生文本型PDF（即你用Word导出的PDF）。如果你的业务场景里有大量扫描件，就必须在pdf-parse前加一层OCR预处理（比如Tesseract.js），或者直接切换到pdfjs-dist。但在本项目中，作者选用的是亚马逊股东信这种标准出版物PDF，纯文本，pdf-parse是性价比最高的选择。

2.3 向量存储为何默认用InMemoryVectorStore？它真的够用吗？

原始代码没显式写出向量存储的初始化，这意味着LangChain默认使用了内存向量库（InMemoryVectorStore）。这绝不是偷懒，而是一个精妙的“渐进式设计”。对于一个本地演示项目，它的目标是先让“检索”这件事发生，再优化“检索”的性能。InMemoryVectorStore的好处是：零配置、启动快、调试直观。你console.log(vectorStore)能看到所有向量的维度和相似度分数，这对理解语义搜索的底层原理（比如余弦相似度如何计算）至关重要。

但它显然不能用于生产。内存向量库无法持久化，重启Node进程就全丢了；它不支持分布式，单机内存总有上限；它没有索引优化，当文档量从8页涨到8000页时，检索速度会线性下降。所以，这个设计的潜台词是：“当你确认流程跑通后，下一步就是把InMemoryVectorStore替换成Chroma或Qdrant”。Chroma是Python生态的明星向量库，但LangChain提供了JS版客户端，可以无缝对接；Qdrant则以Rust编写，性能彪悍，且原生支持Docker一键部署。选哪个？取决于你的技术栈偏好：如果团队主力是JS/TS，Chroma的JS SDK更成熟；如果追求极致性能和未来扩展性，Qdrant是更长远的选择。

3. 核心细节解析与实操要点拆解

3.1 Document对象的深层结构与元数据价值

原始代码里打印出的docs.length是8，这只是冰山一角。一个Document对象远不止pageContent和metadata两个字段那么简单。我们来深挖一下它的完整结构：

{ pageContent: "致股东的一封信\n\n尊敬的股东们：\n\n2023年是充满挑战的一年……", metadata: { source: './pdfs/letter-to-shareholders-amazon.pdf', pdf: { version: '1.10.100', info: { // PDF文档信息，包含作者、创建软件、日期等 Author: 'Amazon.com, Inc.', Creator: 'Adobe InDesign 18.4 (Windows)', Producer: 'Adobe PDF Library 23.1.157', CreationDate: 'D:20240315102234-07\'00\'', ModDate: 'D:20240315102234-07\'00\'' }, metadata: null, totalPages: 8 }, loc: { pageNumber: 1 // 当前Document对应的PDF页码 } }, id: undefined // LangChain自动生成的唯一ID，用于去重 }

这个结构的设计，体现了LangChain对真实业务场景的深刻理解。metadata.loc.pageNumber是法律合规的基石——当你检索到“亚马逊承诺将碳中和目标提前至2040年”，系统必须能立刻告诉你这句话在PDF的第3页，否则这份检索结果在审计报告中毫无意义。metadata.pdf.info.Creator则揭示了文档的生成源头，这对于判断信息可信度（比如，一份由Adobe InDesign生成的正式年报，比一份由WPS生成的草稿，权重更高）提供了依据。而id字段，虽然原始代码里是undefined，但当你后续做批量加载时，LangChain会自动为每个Document生成UUID，避免同一份PDF被重复加载导致向量库污染。

实操心得：我建议在PDFLoader之后，立即对docs数组做一次元数据增强。比如，添加一个chunkId字段，格式为"amazon_2023_letter_p3"，这样在后续调试时，看到向量ID就能立刻对应到具体文档和页码，极大提升排查效率。代码只需一行：

docs = docs.map((doc, idx) => ({ ...doc, id: `amazon_2023_letter_p${doc.metadata.loc.pageNumber}` }));

3.2 文本切片（Text Splitting）的致命陷阱与黄金参数

原始代码里完全没有出现TextSplitter，这是一个巨大的隐患。PDFLoader按页加载，意味着pageContent可能长达数千字。如果直接把整页文本喂给Embedding模型，后果很严重：第一，超出模型的最大上下文长度（如text-embedding-3-small是8191 token），API直接报错；第二，Embedding向量会变得“平庸”，因为它被迫压缩了太多不相关的信息，导致“物流”和“云计算”这两个核心词的向量距离被稀释。

LangChain提供了多种切片器，最常用的是RecursiveCharacterTextSplitter。它的参数设置，是决定语义搜索质量的分水岭：

const { RecursiveCharacterTextSplitter } = require("@langchain/textsplitters"); const textSplitter = new RecursiveCharacterTextSplitter({ chunkSize: 1000, // 每个文本块的目标字符数 chunkOverlap: 200, // 相邻块重叠的字符数，防止语义断裂 separators: ["\n\n", "\n", " ", ""] // 分割优先级：先按双换行，再单换行，再空格 });

这里的关键是chunkSize和chunkOverlap的平衡。chunkSize=1000不是拍脑袋定的。它基于一个经验公式：Embedding模型的token数 ≈ 字符数 × 0.75（英文为主时）。1000字符 ≈ 750 token，远低于8191的上限，留出了安全余量。而chunkOverlap=200，是为了保证语义连贯。想象一下，一段关于“AWS全球基础设施”的描述，如果被硬生生切在“全球”和“基础设施”之间，那么“全球”这个词的Embedding就会失去上下文，变成一个孤立的、无意义的向量。200字符的重叠，足以覆盖一个完整的句子或短语。

注意：切片器的separators参数，是中文用户的“雷区”。原始代码的separators是为英文优化的。如果你处理的是中文PDF，必须把" "（空格）移到最后，把"。"、"！"、"？"加到前面，否则切片会把一句话切成“我们正在建设”和“全国性的物流网络”，彻底破坏语义。正确的中文配置是：

separators: ["\n\n", "\n", "。", "！", "？", "，", "；", "：", "“", "”", "‘", "’", " ", ""]

3.3 Embedding模型的本地化部署与性能权衡

原始代码没指定Embedding模型，意味着它会走LangChain的默认路径——调用OpenAI API。这违背了“本地化”的初衷。要真正实现离线运行，必须引入本地Embedding模型。目前最成熟的方案是@xenova/transformers，它能在浏览器和Node.js中直接运行Hugging Face上的开源模型。

我实测过三个主流模型：

• Xenova/all-MiniLM-L6-v2：轻量级，28MB，推理快，适合原型验证。但它在专业术语（如“AWS Outposts”、“Graviton芯片”）上的区分度一般。
• Xenova/bge-small-en-v1.5：中量级，120MB，精度显著提升，对长尾技术名词理解更好，是生产环境的推荐起点。
• Xenova/bge-large-en-v1.5：重量级，1.2GB，精度最高，但内存占用大，首次加载慢。

选择哪个？看你的硬件和场景。如果你的笔记本只有16GB内存，bge-small是唯一选择；如果你有32GB+内存且追求最佳效果，bge-large值得等待那额外的3秒加载时间。

实操心得：本地Embedding模型的首次加载是同步阻塞的，会卡住整个Node进程。必须用await确保它加载完成后再进行后续操作。我在index.js开头加了这段防御性代码：

console.time("Embedding Model Load"); const { pipeline } = await import("@xenova/transformers"); const extractor = await pipeline("feature-extraction", "Xenova/bge-small-en-v1.5"); console.timeEnd("Embedding Model Load"); // 输出类似 "Embedding Model Load: 2.345s"

这样，每次启动都能看到模型加载耗时，方便你评估是否需要升级硬件或降级模型。

4. 完整实操过程与核心环节实现

4.1 从零开始的完整项目搭建（含避坑指南）

我们抛弃原始代码里模糊的“在新目录中创建”，来一次手把手的、带血泪教训的搭建。假设你的项目根目录叫local-semantic-search。

第一步：初始化项目与安装核心依赖

mkdir local-semantic-search && cd local-semantic-search npm init -y # 安装LangChain生态核心 npm install @langchain/community @langchain/core @langchain/textsplitters # 安装PDF解析器 npm install pdf-parse # 安装本地Embedding模型运行时 npm install @xenova/transformers # 安装向量存储（这里先用内存版，为后续升级铺路） npm install @langchain/langgraph

注意：@langchain/langgraph看似是图计算库，但它包含了LangChain最新版的InMemoryVectorStore实现。旧版@langchain/vectorstores已废弃，强行安装会导致版本冲突，这是我在三个不同项目里踩过的坑。

第二步：准备PDF与目录结构在项目根目录下，创建pdfs文件夹，把letter-to-shareholders-amazon.pdf放进去。关键点来了：PDF文件名里不能有空格或中文！原始代码里./pdfs/letter-to-shareholders-amazon.pdf是安全的，但如果你命名为亚马逊股东信2023.pdf，pdf-parse会因路径编码问题直接报错。务必用英文下划线命名。

第三步：编写index.js——逐行解析

// 1. 导入核心模块 import { PDFLoader } from "@langchain/community/document_loaders/fs/pdf"; import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters"; import { Chroma } from "@langchain/community/vectorstores/chroma"; // 预留升级接口 import { HuggingFaceTransformersEmbeddings } from "@langchain/community/embeddings/hf_transformers"; // 2. 加载PDF（注意：ESM模块需在package.json中设"type": "module"） const loader = new PDFLoader("./pdfs/letter-to-shareholders-amazon.pdf"); console.log("✅ 正在加载PDF..."); const rawDocs = await loader.load(); console.log(`✅ 成功加载 ${rawDocs.length} 页`); // 3. 增强元数据（实操心得：加上这一行，调试效率翻倍） const docs = rawDocs.map((doc, idx) => ({ ...doc, id: `amazon_letter_p${doc.metadata.loc.pageNumber}` })); // 4. 文本切片（中文用户请务必修改separators！） const textSplitter = new RecursiveCharacterTextSplitter({ chunkSize: 1000, chunkOverlap: 200, separators: ["\n\n", "\n", "。", "！", "？", "，", "；", "：", "“", "”", "‘", "’", " ", ""] }); console.log("✅ 正在切片文本..."); const splitDocs = await textSplitter.splitDocuments(docs); console.log(`✅ 切片完成，共生成 ${splitDocs.length} 个文本块`); // 5. 初始化本地Embedding模型（这才是真正的本地化！） console.log("✅ 正在加载本地Embedding模型..."); const embeddings = new HuggingFaceTransformersEmbeddings({ model: "Xenova/bge-small-en-v1.5" }); // 6. 创建向量存储（此处用Chroma，为持久化铺路） // 注意：Chroma需要Python环境，若未安装，会自动回退到内存版，但会警告 console.log("✅ 正在构建向量索引..."); const vectorStore = await Chroma.fromDocuments(splitDocs, embeddings, { collectionName: "amazon_shareholder_letter", // persistDirectory: "./chroma_db" // 取消注释即可开启持久化 }); // 7. 执行语义搜索（核心！） console.log("✅ 正在执行语义搜索..."); const query = "What are Amazon's key investments in logistics infrastructure for 2023?"; const results = await vectorStore.similaritySearch(query, 3); // 返回最相关的3个块 console.log("\n🔍 搜索结果："); results.forEach((result, idx) => { console.log(`\n--- 结果 ${idx + 1} ---`); console.log(`📄 来源: ${result.metadata.source} (第${result.metadata.loc.pageNumber}页)`); console.log(`💡 匹配度: ${(result.metadata.score * 100).toFixed(1)}%`); console.log(`📝 内容: ${result.pageContent.substring(0, 200)}...`); });

第四步：关键配置——package.json的生死线原始代码只提了一句“加type字段”，但没说清全部。你的package.json必须包含：

{ "type": "module", "engines": { "node": ">=18.0.0" }, "scripts": { "start": "node index.js" } }

"type": "module"是ESM语法的前提；"engines"指定了最低Node版本，因为@xenova/transformers依赖Node 18的WebAssembly特性；"start"脚本让你能用npm start一键运行，而不是每次都敲node index.js。

4.2 语义搜索的底层计算过程可视化

当vectorStore.similaritySearch(query, 3)被执行时，后台发生了什么？我们来拆解这个“黑盒”：

1. Query Embedding：你的问题"What are Amazon's key investments..."被送入bge-small-en-v1.5模型，输出一个768维的浮点数向量。这个向量不是随机的，它在数学空间里，与“物流”、“投资”、“2023”、“亚马逊”这些词的向量距离很近，而与“苹果”、“手机”、“iOS”距离很远。

2. Vector Store Lookup：向量库（Chroma）收到这个查询向量后，不会暴力遍历所有768维向量计算余弦相似度（那太慢了）。它使用了HNSW（Hierarchical Navigable Small World）算法。你可以把它想象成一个“多层导航地图”：顶层是几个超级节点，指向几个大区域；中层是区域内的主要街道；底层才是具体的门牌号。HNSW先在顶层快速定位到“物流”这个大区域，再逐层下钻，最终找到最接近的3个文本块向量。这个过程，比暴力搜索快100倍以上。

3. Score Calculation：对找到的3个候选向量，Chroma会精确计算它们与查询向量的余弦相似度：

   cosθ = (A·B) / (||A|| × ||B||)

   其中A是查询向量，B是文档向量，A·B是点积，||A||是向量模长。结果是一个-1到1之间的数，越接近1，语义越相似。score字段返回的就是这个值。

实操心得：我曾遇到一个诡异问题——搜索"logistics"返回了高分，但搜索"fulfillment centers"却得分很低。排查发现，fulfillment centers在PDF里是作为一个专有名词出现的，而bge-small模型的词汇表里没有这个词，它被切成了fulfill和ment两个子词，语义失真。解决方案是：在切片后，对splitDocs做一次简单的同义词映射：

const synonymMap = { "fulfillment centers": "fulfillment centers", "FCs": "fulfillment centers", "warehouses": "fulfillment centers" }; splitDocs = splitDocs.map(doc => { let content = doc.pageContent; Object.entries(synonymMap).forEach(([key, value]) => { content = content.replace(new RegExp(key, 'gi'), value); }); return { ...doc, pageContent: content }; });

这种“土办法”，在模型能力不足时，往往比换模型更有效。

5. 常见问题与排查技巧实录

5.1 “Error: Cannot find module ‘pdf-parse’” —— Node.js模块解析的隐秘规则

这个问题90%的初学者都会遇到。根本原因不是pdf-parse没装，而是Node.js的模块解析机制在作祟。pdf-parse是一个CommonJS模块（.cjs），而你的index.js是ESM模块（.js且package.json里有"type": "module"）。Node.js默认不允许ESM直接importCommonJS模块。

解决方案有且仅有两个：

1. 推荐方案：用动态import()
   把pdf-parse的引入，从顶部的静态import，改为函数内部的动态import：

   // ❌ 错误：静态import // import * as pdfParse from "pdf-parse"; // ✅ 正确：动态import const pdfParse = await import("pdf-parse"); const data = await pdfParse.default(buffer); // 注意：default是实际函数

2. 备选方案：改用.cjs后缀
   把index.js重命名为index.cjs，并在package.json里删除"type": "module"。但这会让整个项目退回到CommonJS时代，放弃ESM的诸多优势，不推荐。

排查技巧：当你看到这个错误时，第一反应不是重装包，而是检查node_modules/pdf-parse/package.json。如果里面没有"type": "commonjs"或"main"字段指向一个.cjs文件，那基本可以确定是模块系统不兼容。此时，npm list pdf-parse命令会显示UNMET PEER DEPENDENCY，这就是线索。

5.2 “TypeError: Cannot read property ‘length’ of undefined” —— PDFLoader的静默失败

这个错误通常出现在loader.load()之后，docs是undefined。根本原因只有一个：pdf-parse解析失败，但没有抛出异常，而是返回了null。PDFLoader内部没有做空值校验，直接对null调用了.length。

触发场景有三个：

• PDF文件路径错误（比如./pdfs/少了个s，变成了./pdf/）；
• PDF是扫描版（pdf-parse对扫描PDF返回空）；
• PDF有密码保护（pdf-parse无法处理加密PDF）。

终极排查法：在loader.load()后加一行日志

const rawDocs = await loader.load(); console.log("Raw Docs:", rawDocs); // 如果是undefined，立刻就知道是Loader失败 if (!rawDocs || rawDocs.length === 0) { throw new Error("PDFLoader failed to parse the document. Check if the PDF is text-based and not encrypted."); }

实操心得：我给自己写了一个safePDFLoader封装函数，它会自动检测PDF类型：

async function safePDFLoader(filePath) { const buffer = await fs.readFile(filePath); // 尝试用pdf-parse解析 const { default: pdfParse } = await import("pdf-parse"); try { const data = await pdfParse(buffer); if (!data.text || data.text.trim().length < 100) { throw new Error("PDF appears to be scanned or empty"); } return new PDFLoader(filePath); } catch (e) { throw new Error(`PDF parsing failed: ${e.message}`); } }

5.3 搜索结果“驴唇不对马嘴”——Embedding模型与领域适配的真相

这是最让人沮丧的问题：明明问题很清晰，但返回的却是风马牛不相及的内容。比如问“亚马逊的云计算收入是多少？”，结果返回了“物流配送时间缩短了20%”。这不是代码bug，而是Embedding模型的领域偏置在作怪。

bge-small-en-v1.5是在通用语料上训练的，它对“云计算”（cloud computing）和“物流”（logistics）的向量距离，可能比对“云计算”和“服务器”（server）的距离还要远。因为训练数据里，“物流”和“配送”、“仓库”一起出现的频率，远高于“云计算”和“服务器”。

解决方案是微调（Fine-tuning），但成本太高。更务实的做法是：

1. Query Rewriting（查询重写）：在发送查询前，用一个轻量LLM（如Phi-3-mini）帮你“翻译”问题。例如，把"What is AWS revenue?"重写为"Find the total revenue figure for Amazon Web Services in the 2023 annual report"。这个重写过程，把模糊的自然语言，转化成了向量搜索更易理解的、带实体和年份的精确描述。
2. Hybrid Search（混合搜索）：不放弃关键词搜索。用fuse.js做一个轻量级的全文关键词匹配，再用LangChain做语义匹配，最后把两个结果按权重（比如70%语义+30%关键词）融合排序。代码框架如下：

   // 关键词搜索（基于pageContent） const keywordResults = fuse.search(query).slice(0, 3); // 语义搜索 const semanticResults = await vectorStore.similaritySearch(query, 3); // 融合 const hybridResults = [...keywordResults, ...semanticResults].sort( (a, b) => (b.score || 0) - (a.score || 0) ).slice(0, 3);

最后分享一个小技巧：在调试阶段，永远不要只看pageContent。一定要打印出metadata里的loc.pageNumber和source。我曾经花了3小时排查一个“搜索不到”的问题，最后发现，是因为PDF的第5页是纯图片（一张图表），pdf-parse返回了空字符串，导致切片后那个位置的向量是全零向量，而全零向量与任何查询向量的余弦相似度都是0，自然排不到前面。看到pageNumber: 5，一切就豁然开朗。

6. 从本地演示到生产就绪的演进路径

这个项目的价值，不在于它现在能做什么，而在于它为你铺设了一条清晰的、可量化的演进路线。从node index.js输出第一行8，到支撑一个百人团队的知识库，中间只有四步，每一步都有明确的技术选型和验收标准。

第一步：从内存到持久化（1天）
目标：重启服务后，向量索引不丢失。
行动：取消Chroma.fromDocuments(...)中的persistDirectory注释，指向一个本地文件夹（如./chroma_db）。Chroma会自动将向量和元数据序列化到该目录。
验证：npm start两次，第二次启动时，Chroma.fromDocuments会从磁盘加载已有索引，而不是重新计算。控制台日志会显示Loading collection from disk。

第二步：从单文档到多文档（2天）
目标：支持同时加载100份PDF，且能区分来源。
行动：改造PDFLoader为循环加载，为每个Document的metadata添加docId和docType字段（如{ docId: "amzn_2023_letter", docType: "shareholder_letter" }）。
验证：搜索"carbon neutrality"，结果里metadata.docId应正确显示为amzn_2023_letter，而非amzn_2022_letter。

第三步：从命令行到Web界面（3天）
目标：非技术人员也能用浏览器提问。
行动：用Express.js搭一个极简API：

app.post("/search", async (req, res) => { const { query } = req.body; const results = await vectorStore.similaritySearch(query, 5); res.json({ results }); });

前端用HTML+JS调用此API，实现一个搜索框。
验证：打开http://localhost:3000，输入问题，看到JSON结果在浏览器里渲染出来。

第四步：从单机到集群（1周）
目标：支持1000并发查询，响应时间<500ms。
行动：将Chroma替换为Qdrant。Qdrant是Rust写的，原生支持Docker和gRPC，单节点轻松扛住5000 QPS。
部署命令：

docker run -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage:z qdrant/qdrant

然后在代码中，把Chroma.fromDocuments换成Qdrant.fromDocuments，指向http://localhost:6333。
验证：用autocannon压测：autocannon -u http://localhost:3000/search -b '{"query":"logistics"}' -c 1000 -d 30，观察平均延迟和错误率。

这条路，我带着三个不同行业的客户走过。从第一份PDF加载成功，到最终上线，最短的一次只用了11天。它之所以可行，是因为每一步都建立在前一步的坚实基础上，没有一步是空中楼阁。你不需要一开始就规划Qdrant，就像你不需要在学骑自行车时就研究空气动力学。先让车轮转起来，再考虑如何让它飞得更高。这个项目，就是那辆你一定能骑起来的自行车。