企业做 AI 知识库2025 年最主流的技术方案已经不是“把整份文档喂给大模型”而是 RAGRetrieval-Augmented Generation检索增强生成。这篇不铺垫背景直接拆解一个“NestJS Langchain.js 向量数据库”的 RAG 全栈知识库项目从工程目录设计、后端服务搭建、文档解析、文本切块、向量化入库到检索问答 API、前端接入、Docker 与宝塔部署、效果验证、问题排查完整走一遍。如果你正在做企业级后台管理系统、AI 客服、内部文档助手或者打算从前端/后端转 AI 全栈这篇文章可以直接按流程跟练。为什么选 NestJS Langchain.js 这套组合而不是 Python 后端核心原因是 TypeScript 全链路。NestJS 提供模块化、依赖注入、守卫、拦截器、生命周期管理等企业级后端能力Langchain.js 是 LangChain 的 TypeScript 实现提供文档加载器、文本切块器、Embedding 模型封装、向量库连接器、Prompt 模板和检索链。前后端和 AI 编排共用一套类型系统工程落地比“Node 前端 Python 后端”的双语言方案更顺也更容易在企业团队里维护。整个系统最核心的链路是文档上传 → 解析清洗 → 文本切块 → Embedding 向量化 → 写入向量数据库 → 用户提问 → 语义检索 TopK → 组装 Prompt → 大模型生成回答。下面我会把这条链路拆成工程实现给出可以复制改造的 NestJS 模块代码、Langchain.js 检索链代码、API 调用示例和部署配置。先看这个项目到底能做什么、门槛在哪里。1. 核心能力速览能力项说明项目类型AI 全栈应用 / 企业级 RAG 知识库问答系统后端框架NestJSNode.js TypeScript需 Node.js 18建议 20 LTSAI 编排框架Langchain.jsLangChain TypeScript 版本核心功能文档管理、文本解析、切块、向量化、语义检索、生成式问答、多轮会话典型组件PostgreSQL pgvector、Redis缓存/任务队列、MinIO文件存储、大模型 API模型接入方式OpenAI 兼容接口或本地模型服务通过环境变量切换前端方案可选 Next.js / Vue3也可先只做 RESTful API 简易管理页启动方式本地 npm 启动 / Docker Compose 一键编排是否支持 API支持提供文档上传、检索问答、会话历史等 RESTful 接口是否支持批量任务支持多文档可批量解析、切块、向量化入库配合 Redis 任务队列显存需求取决于所用的大模型和 Embedding 模型。调云端 API 无需本地 GPU本地部署模型需按模型量级评估适合场景企业内部知识库、客服问答、研发文档助手、产品文档检索、法律/合规文档复核从能力表可以看出这套方案不是拿一个大模型聊天那么简单。它的重点是把“文档怎么进、知识怎么存、问题怎么检索、答案怎么生成”做成一条标准流水线最后暴露成接口给前端或第三方系统调用。对企业来说RAG 的价值在于知识可以持续更新不依赖微调也不用把私有数据直接暴露给模型厂商。要注意的是显存占用和部署资源不能拍脑袋写死。如果底座模型调用云端 API后端只需要一台普通 2 核 4G 的云服务器如果要在本地跑 7B/13B 开源模型才需要考虑独立 GPU 机器。实际资源消耗取决于模型参数量、Embedding 模型、并发数和向量库规模建议先以最小配置跑通再逐步扩容。2. 适用场景与使用边界这类企业级 RAG 系统最适合解决三类问题第一企业内部文档太多且分散员工找不到答案第二客服或运营团队反复回答相似问题需要统一知识出口第三需要基于指定文档做审查、复核或内容生成例如产品说明书、操作手册、合同模板。通过接入 NestJS 的管理后台运营人员可以上传文档、查看入库状态、测试检索质量而不需要直接接触数据库和模型配置。这套系统也有明显的边界不要指望一个 RAG 项目解决所有 AI 问题。RAG 不会“无中生有地学会”文档里没有的知识检索不到的内容生成端照样会答错RAG 也不等于微调如果目标是让模型学习某种业务写法或风格应该考虑领域微调而不是只做知识库此外RAG 对文档质量很敏感扫描版 PDF、手写笔记、表格混排类文档直接解析入库的效果通常不理想。合规和授权问题必须放在前面说清楚。上传到知识库的文档务必确认内容来源合法拥有使用和分发的授权涉及客户隐私、内部财务、人员信息的文档要做权限分级接口层和文档层都要加访问控制如果使用云端大模型 API敏感数据是否可以被模型厂商处理需要提前确认企业安全合规要求。生产环境建议对知识库做“最小可见范围”设计而不是所有员工都能检索全部文档。3. 整体架构与工程目录设计一个可维护的企业级 RAG 项目建议拆成六层接入层前端/API 网关、应用层NestJS 业务模块、AI 编排层Langchain.js 链、数据层PostgreSQL、pgvector、Redis、MinIO、模型层大模型 API 或本地推理服务、基础设施层Docker、Nginx、日志监控。每一层职责单一后续替换模型或向量库时不会牵动整个系统。前端页面 / 管理后台 │ REST API / WebSocket ▼ NestJS 应用服务 ├── 用户与权限模块 ├── 文档管理模块 ├── 解析切块模块 ├── 向量化与检索模块 ├── 会话问答模块 └── 批量任务模块 │ ├── PostgreSQL pgvector业务数据 向量索引 ├── Redis缓存 / BullMQ 任务队列 ├── MinIO / 对象存储原始文档 └── 大模型 API / 本地模型服务Embedding ChatNestJS 的模块化在这里很合适。文档管理、知识库、会话、任务队列各自做成 Module每个 Module 内部再分 Controller、Service、Entity、DTO。实际工程可以按下面的目录组织src/ ├── modules/ │ ├── auth/ # 登录、鉴权、用户管理 │ ├── document/ # 文档上传、列表、删除 │ ├── knowledge/ # 知识库配置、切块参数 │ ├── ingestion/ # 解析、切块、向量化入库 │ ├── retrieval/ # 检索服务封装 │ ├── chat/ # 对话接口、会话历史 │ └── task/ # 批量任务队列 ├── common/ │ ├── filters/ # 全局异常过滤器 │ ├── interceptors/ # 日志、响应统一包装 │ └── guards/ # 权限守卫 ├── config/ # 环境变量、数据库配置 └── main.ts推荐用官方脚手架初始化 NestJS 工程后面所有模块都基于这个骨架扩展。NestJS 的依赖注入让模型客户端、向量库连接、配置中心可以被多个服务复用不会出现“每个模块各连一次模型”的重复代码。4. 环境准备与前置条件先列一份完整的环境清单。软件版本选择以稳定和团队熟悉度为优先没有绝对标准但下面的组合是目前企业项目里出现频率较高的。组件建议说明Node.js18 或 20 LTSNestJS 10/11 均支持20 LTS 更稳包管理器pnpm 或 npm团队统一即可PostgreSQL14 及以上需要支持 pgvector 扩展pgvector最新稳定版向量索引依赖Redis6.x / 7.xBullMQ 任务队列和会话缓存MinIO最新稳定版可选文件量大时使用大模型 APIOpenAI 兼容接口或本地服务需准备 API Key 和模型名称Docker20.10可选但推荐生产环境使用代码仓库Git配合 CI/CD 发布本地开发时可以先不装 MinIO文件存本地磁盘即可但 PostgreSQL 的 pgvector 扩展必须装好因为向量存储直接依赖它。验证 pgvector 是否可用执行CREATE EXTENSION IF NOT EXISTS vector; SELECT extversion FROM pg_extension WHERE extname vector;模型接入需要确认两件事Embedding 模型和对话模型。Embedding 负责把文本转成向量对话模型负责生成最终答案。生产环境可以直接用 OpenAI 兼容接口也可以接入国内厂商的兼容端点或者用 Ollama / vLLM 部署本地开源模型。项目里建议把模型配置全部放到.env这样切换模型不动代码。5. NestJS 后端工程搭建先用脚手架创建项目然后安装数据库和 Langchain.js 相关依赖。# 创建 NestJS 项目 nest new enterprise-rag-server --package-manager pnpm cd enterprise-rag-server # 数据库与配置 pnpm add nestjs/config nestjs/typeorm typeorm pg nestjs/platform-express # Langchain.js 核心与模型接入 pnpm add langchain langchain/core langchain/openai langchain/community langchain/textsplitters # 文档解析 pnpm add pdf-parse mammoth marked # 任务队列 pnpm add nestjs/bullmq bullmq安装完成后先配置全局模块。app.module.ts里引入 ConfigModule 和 TypeOrmModule数据库连接信息从环境变量读取// src/app.module.ts import { Module } from nestjs/common; import { ConfigModule, ConfigService } from nestjs/config; import { TypeOrmModule } from nestjs/typeorm; Module({ imports: [ ConfigModule.forRoot({ isGlobal: true }), TypeOrmModule.forRootAsync({ inject: [ConfigService], useFactory: (config: ConfigService) ({ type: postgres, host: config.get(DB_HOST, 127.0.0.1), port: config.getnumber(DB_PORT, 5432), username: config.get(DB_USER, postgres), password: config.get(DB_PASSWORD, postgres), database: config.get(DB_NAME, rag_kb), autoLoadEntities: true, synchronize: true, // 生产环境请改为 false使用 migration 管理 }), }), ], }) export class AppModule {}synchronize: true只适合开发环境因为频繁改动实体可能造成数据不一致。生产环境建议关闭用 TypeORM migration 管理表结构变更。文档模块是知识库的入口。实体设计上文档表和文本块表分开文档表保存文件元信息文本块表保存切块内容和向量。这样做的好处是删除文档时能级联清理向量数据检索时也能快速回溯到来源文档。// src/modules/document/entities/document.entity.ts import { Column, CreateDateColumn, Entity, PrimaryGeneratedColumn } from typeorm; Entity(documents) export class DocumentEntity { PrimaryGeneratedColumn(uuid) id: string; Column() title: string; Column({ default: pending }) status: string; // pending / processing / completed / failed Column({ nullable: true }) filePath: string; Column({ default: 0 }) chunkCount: number; CreateDateColumn() createdAt: Date; }文本块表需要额外存向量字段。pgvector 配合 TypeORM 时可以用vector类型但类型定义需要和 pgvector 类型对应。实际项目中通常写一个自定义类型映射或者在插入向量前用原生 SQL 设置类型。更简单的做法是业务元数据放在 TypeORM 实体向量字段通过 TypeORM 的query()或 Repository 的queryBuilder执行原生 SQL 写入避免类型映射问题。6. Langchain.js 与 RAG 核心链路实现RAG 的核心在 Langchain.js 的检索链。先创建模型客户端和 Embedding 客户端代码里统一走环境变量// src/common/ai/llm.provider.ts import { ChatOpenAI } from langchain/openai; import { OpenAIEmbeddings } from langchain/openai; export function createChatModel() { return new ChatOpenAI({ model: process.env.LLM_MODEL || gpt-4o-mini, apiKey: process.env.LLM_API_KEY, configuration: { baseURL: process.env.LLM_BASE_URL, // 兼容 OpenAI 的接口地址 }, temperature: 0.2, }); } export function createEmbeddings() { return new OpenAIEmbeddings({ model: process.env.EMBEDDING_MODEL || text-embedding-3-small, apiKey: process.env.EMBEDDING_API_KEY || process.env.LLM_API_KEY, configuration: { baseURL: process.env.EMBEDDING_BASE_URL, }, }); }这里用baseURL是为了兼容各类“OpenAI 协议”的模型服务包括国内厂商的兼容端点、Ollama 的 OpenAI 兼容接口、以及自建的 vLLM 服务。切换模型时只改.env不碰业务代码。检索问答链路推荐用 Langchain.js 的createRetrievalChain组装。先构造 Prompt 模板再创建“文档拼接链”最后把检索器接进来// src/modules/chat/rag.service.ts import { Injectable } from nestjs/common; import { ChatPromptTemplate } from langchain/core/prompts; import { createStuffDocumentsChain } from langchain/chains/combine_documents; import { createRetrievalChain } from langchain/chains/retrieval; import { createChatModel, createEmbeddings } from ../../common/ai/llm.provider; import { VectorStoreService } from ../retrieval/vector-store.service; Injectable() export class RagService { constructor(private readonly vectorStoreService: VectorStoreService) {} async buildChain() { const prompt ChatPromptTemplate.fromMessages([ [system, 你是一个企业知识库助手。请仅根据以下资料回答问题。如果资料中没有相关信息请直接说“资料中未找到相关内容”不要编造。\n\n资料\n{context}], [human, 问题{input}], ]); const combineDocsChain await createStuffDocumentsChain({ llm: createChatModel(), prompt, }); const retriever this.vectorStoreService.getVectorStore().asRetriever(8); return createRetrievalChain({ retriever, combineDocsChain, }); } async ask(question: string) { const chain await this.buildChain(); const response await chain.invoke({ input: question }); return response.answer; } }这段代码是 RAG 链路最短也最稳的写法。asRetriever(8)表示每次检索返回 8 个相关文本块temperature调低让模型更忠实于资料系统提示词里强制要求“没有资料就说没有”能明显减少幻觉。如果要做多轮会话可以在ask方法里先把用户问题做一次“改写”。常见做法是把历史对话和当前问题一起交给大模型让它生成一个完整上下文的新问题再拿这个问题去检索。这样做比直接把历史拼进 RAG 的检索输入更准确因为向量检索本身不擅长带上下文的模糊表达。7. 知识库处理解析、切块与向量化文档入库是整个 RAG 系统里最影响效果的一环。这部分的顺序是上传 → 解析 → 清洗 → 切块 → Embedding → 写入向量库。任何一个环节做不好检索质量都会明显下降。解析阶段不同文件类型走不同解析器。Markdown 可以直接读文本PDF 用pdf-parseWord 用mammoth把 docx 转成 HTML 或纯文本。要注意的是扫描版 PDF 没有文本层必须接 OCR常规解析方案处理不了。解析后要做基础清洗去掉页眉页脚、多余空行、无意义的超链接和表格乱码。切块策略是整个项目里最值得调优的参数。Langchain.js 的RecursiveCharacterTextSplitter是最常用的切块器它会按照分隔符优先级把文本切成块import { RecursiveCharacterTextSplitter } from langchain/textsplitters; const splitter new RecursiveCharacterTextSplitter({ chunkSize: 500, chunkOverlap: 80, separators: [\n\n, \n, 。, , , , , ], }); const chunks await splitter.splitText(cleanedText); console.log(切块数量${chunks.length});chunkSize和chunkOverlap要结合文档语言和 Embedding 模型的最大输入长度来调。中文文档建议chunkSize在 400 到 800 之间太小会导致上下文不完整太大则 Embedding 语义被稀释。chunkOverlap控制在 10% 到 20%让相邻块之间有重叠避免关键句子正好落在切分边界上。更进阶的方案是语义切块和“小到大检索”。语义切块利用 Embedding 判断文本主题变化在主题切换处切分小到大检索则是把小块用于检索命中后把更大范围的上下文一并交给大模型。这两种方案都值得在文档质量要求高的场景下尝试。向量化入库时如果用的是 pgvectorLangchain.js 的PGVectorStore可以直接把Document列表写入数据库// src/modules/retrieval/vector-store.service.ts import { Injectable } from nestjs/common; import { PGVectorStore } from langchain/community/vectorstores/pgvector; import { ConfigService } from nestjs/config; import { createEmbeddings } from ../../common/ai/llm.provider; Injectable() export class VectorStoreService { constructor(private readonly config: ConfigService) {} async getVectorStore() { return PGVectorStore.initialize(createEmbeddings(), { postgresConnectionOptions: { host: this.config.get(DB_HOST, 127.0.0.1), port: this.config.getnumber(DB_PORT, 5432), user: this.config.get(DB_USER, postgres), password: this.config.get(DB_PASSWORD, postgres), database: this.config.get(DB_NAME, rag_kb), }, tableName: document_embeddings, columns: { idColumnName: id, contentColumnName: content, metadataColumnName: metadata, vectorColumnName: embedding, }, }); } async addDocuments(documents: { pageContent: string; metadata: Recordstring, any }[]) { const store await this.getVectorStore(); await store.addDocuments(documents); } }入库前要检查 pgvector 查询性能。数据量小时无所谓数据量上来之后必须给向量列建索引。pgvector 支持 HNSW 和 IVFFlat 两种索引HNSW 查询精度更高、构建慢一些IVFFlat 构建快、查询快但参数需要调。生产环境推荐 HNSWCREATE INDEX ON document_embeddings USING hnsw (embedding vector_cosine_ops);批量任务用 BullMQ 来做。文档上传后NestJS 服务把“解析 切块 向量化”任务投递到 Redis 队列Worker 消费任务。这样有两个好处一是大批量文档不会阻塞 API 请求二是任务失败可以重试不会因为一条坏文档导致整个队列停住。任务状态可以记录在 documents 表里前端管理后台轮询即可。8. 检索问答 API 与批量任务后端对外暴露的接口建议分为三组文档管理接口、知识库处理接口、问答接口。下面是最小可用的接口设计方法路径说明POST/api/documents/upload上传文档GET/api/documents文档列表与状态DELETE/api/documents/:id删除文档及对应向量POST/api/documents/:id/process触发单文档入库POST/api/admin/batch-import批量导入目录或压缩包POST/api/chat/ask提问并获取回答GET/api/chat/history/:sessionId获取会话历史问答接口的请求和返回建议统一成 JSON方便前端和外部系统对接// POST /api/chat/ask { sessionId: abc-123, question: 企业知识库如何配置权限 }{ answer: 根据内部文档企业知识库的权限配置分为三步……, sources: [ { documentId: doc-001, title: 知识库运维手册, content: ……权限配置相关段落…… } ] }把sources来源引用返回给前端非常重要。企业场景里用户不仅要答案还要确认答案来自哪份文档。后续也可以做引用高亮点击来源直接跳转到原文位置。批量导入接口适合处理存量文档。常见做法是管理员把一批 PDF/DOCX/MD 放入某个目录或者上传 zip服务端遍历文件后逐个投递任务。批量任务的进度接口返回“总数、成功数、失败数、正在处理数”这样自然就实现了任务状态可视化。下面是一个 curl 调用批量任务的示例# 触发批量导入 curl -X POST http://127.0.0.1:3000/api/admin/batch-import \ -H Content-Type: application/json \ -H Authorization: Bearer token \ -d { sourceType: directory, sourcePath: /data/kb-docs, chunkSize: 500, chunkOverlap: 80 }Python 调用问答接口的示例也附上方便后续接到其他系统import requests url http://127.0.0.1:3000/api/chat/ask headers {Authorization: Bearer token, Content-Type: application/json} payload { sessionId: py-client-1, question: RAG 的切块参数应该怎么调 } resp requests.post(url, jsonpayload, timeout120) data resp.json() print(data[answer]) for source in data.get(sources, []): print(source[documentId], source[title])批量任务必须考虑失败重试策略。建议设置“失败后自动重试 2 次”并对解析失败的文件记录具体原因。如果是单个文件格式损坏跳过它比阻塞整批更重要如果是模型 API 限流等待时间补偿后重试效果更好。9. 前端接入与生产部署前端可以选择 Next.js、Vue3 Element Plus 或任意能调 REST API 的框架。需要实现的页面包括文档上传与状态页、知识库管理页、问答聊天页、系统配置页。聊天页建议使用 SSEServer-Sent Events或 WebSocket 实现流式输出体验远好于等完整响应。NestJS 返回 SSE 流很简单配合nestjs/platform-express和 Langchain.js 的stream方法即可。如果第一版只做 Web 端可以先不接流式直接返回完整 JSON等基础功能稳定后再优化交互体验。生产部署推荐 Docker Compose。下面是一个最小编排示例包含 NestJS 应用、PostgreSQL、Redis、MinIO 四个服务# docker-compose.yml version: 3.8 services: postgres: image: pgvector/pgvector:pg16 container_name: rag-postgres environment: POSTGRES_DB: rag_kb POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres ports: - 5432:5432 volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 5s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: rag-redis ports: - 6379:6379 minio: image: minio/minio:latest container_name: rag-minio command: server /data --console-address :9001 environment: MINIO_ROOT_USER: minioadmin MINIO_ROOT_PASSWORD: minioadmin ports: - 9000:9000 - 9001:9001 volumes: - miniodata:/data rag-server: build: context: . dockerfile: Dockerfile container_name: rag-server ports: - 3000:3000 env_file: - .env depends_on: postgres: condition: service_healthy redis: condition: service_started restart: unless-stopped volumes: pgdata: miniodata:很多同学问“宝塔支持部署 NestJS 项目吗”答案是支持。宝塔里有两种方式一种是直接用“Node.js 项目”功能选择 Node 版本、入口文件和后端端口加上 Supervisor 守护进程另一种更推荐就是上面这种 Docker Compose 方式宝塔面板可以通过 Docker 管理器安装 Compose 服务点击编排即可启动整套环境。两种方式都需要在宝塔的防火墙和安全组里放行对应端口。部署时还要注意 Nginx 反向代理。前端页面走 80/443/api路径代理到 3000 端口WebSocket 或 SSE 需要额外配置proxy_http_version 1.1、proxy_set_header Connection等参数。HTTPS 证书用免费证书即可接口层再配合 JWT 鉴权避免服务直接暴露在公网。10. 功能测试与效果验证系统跑通之后最怕的是“接口都通但回答质量没法验收”。建议从四个维度做测试基础流程、检索质量、生成质量、稳定性。基础流程测试覆盖完整链路上传一篇 PDF → 等待状态变为 completed → 提问文档相关内容 → 返回答案并带来源文档。这个过程建议用脚本自动跑而不是每次都靠页面点。下面是判断成功的标准文档状态从 pending → processing → completedchunkCount 大于 0。问题能命中文档内容答案包含来源文档。文档删除后再检索相同问题不再返回该文档内容。检索质量测试要建立一份测试集。准备 20 到 50 个真实问题每个问题标注“应该命中的文档或段落”然后跑检索统计命中率。命中率低于 60% 时优先调切块参数和检索 TopK而不是换大模型。这个测试集很关键之后每次调整 Embedding 模型、切块策略、向量索引都用同一份测试集对比效果好坏一目了然。生成质量测试关注三件事答案是否忠于资料、是否回答了问题、是否出现幻觉。建议把问题和对应答案整理成表格由业务人员人工打分分“准确、部分准确、错误、无中生有”四档。对“无中生有”的回答要重点排查是检索没召回相关内容还是 Prompt 约束不够或者模型本身幻觉严重。从工程经验看大部分幻觉问题都是检索召回不佳造成的优先修检索链路。稳定性测试可以用并发请求验证。比如用脚本同时发起 20 个问答请求观察接口响应时间和服务内存。问答接口如果依赖外部模型 API建议加上超时控制和熔断降级模型 API 超时时直接返回“服务繁忙请稍后重试”而不是让用户一直转圈。11. 资源占用与性能观察RAG 系统的性能瓶颈通常不在应用本身而在三个地方模型 API 的响应延迟、向量检索的耗时、文档解析的 CPU 占用。先看延迟链路。一次问答请求的时间大致是Embedding 检索几十到几百毫秒 大模型生成根据模型和输出长度几秒到几十秒。如果用户体感慢优先看是不是模型生成太慢而不是急着加服务器配置。可以在 NestJS 里给/api/chat/ask加日志记录检索耗时和生成耗时分别多少[chat] 检索耗时: 210ms [chat] 生成耗时: 5.8s [chat] 总耗时: 6.1s这样能快速定位瓶颈。检索耗时长检查 pgvector 索引是否生效以及是否把全表扫描跑成了线性查询生成耗时长检查模型选择、输出长度、并发限流。内存占用方面Node.js 服务的堆内存可以通过process.memoryUsage()监控容器部署用docker stats观察。向量检索本身不占太多应用内存因为向量在 PostgreSQL 里但如果用了本地 Embedding 模型模型加载后的内存和显存占用就不能忽略。实际占用需以本机测试为准不同模型差异很大。降低资源占用的常用手段包括Embedding 结果加缓存相同或相似文本不重复向量化检索 TopK 不要盲目调大8 到 10 通常够用批量入库任务控制并发数避免同时解析大量文档导致 CPU 打满PostgreSQL 开启连接池限制防止应用实例多了之后把数据库连接耗尽。12. 常见问题与排查方法问题现象可能原因排查方式解决方案pgvector 扩展无法创建数据库版本过低或未安装插件执行SELECT version();检查 PG 版本使用 pgvector/pgvector 镜像重建数据库检索返回空结果向量库里没有数据或 Embedding 维度不匹配查询 document_embeddings 表是否有记录检查入库任务状态和切块结果中文切块效果差分隔符没有包含中文标点打印切块结果观察断句位置在 separators 里补充“。”等分隔符问答接口超时模型 API 响应慢或网络不稳定查看日志中的生成耗时调大超时时间接入流式输出Docker 中应用连不上数据库连接地址写成 127.0.0.1检查 compose 网络和环境变量容器内改用服务名 postgres 访问宝塔部署后页面 502Nginx 没配代理或服务未启动检查 Nginx 错误日志正确配置 proxy_pass 到 3000 端口模型 API 提示限流请求并发过高查看模型服务返回码加入队列限流和退避重试文档状态一直 processing任务队列消费失败查看 BullMQ worker 日志修复解析异常设置失败重试补一个容易被忽略的问题Embedding 模型切换后向量维度变了但旧数据还在库里会导致查询报错。切换 Embedding 模型时必须清空旧向量数据或重建一份新的向量表不要混用不同模型的向量。建议在建表时把 Embedding 模型名称作为元数据保存查询时带上模型条件避免脏数据干扰检索。另一个高频问题是“为什么答案没有引用我上传的新文档”。多数情况是切块后的向量已经入库但检索的 TopK 结果里相关度排名不够或者新文档和旧知识内容重叠被旧文档挤掉了。解决思路是把新文档的 metadata 加上时间戳和权重字段检索时把时间权重纳入排序或者直接做一个“指定文档 ID 范围检索”的功能管理员可以先锁定期望的文档范围做验证。13. 最佳实践与合规提醒工程上建议先跑通最小闭环再逐步扩展。第一版只需要一个上传接口、一个切块入库流程、一个问答接口、一个简单管理页面。确认链路稳定后再补权限、批量任务、流式输出、监控告警。不要一上来就设计十几个微服务企业内部系统的核心是稳定不是技术炫酷。代码和配置层面环境变量必须隔离。模型 API Key、数据库密码、Redis 密码统一放.env并加入.gitignore。.env.example保留一份模板方便同事快速配置本地环境。生产环境用 Docker 容器时密钥通过环境变量注入不要写死在镜像里。文档管理上建议为每份文档保存状态和版本。企业知识库不是一次性上传就结束文档会被修订、删除、过期。给文档加 version 字段入库时记录文件 hash内容变化时自动触发重新解析这样才能保证用户检索到的不是陈旧内容。批量任务要写日志落库记录每批任务的开始时间、结束时间、成功数和失败原因方便追溯。合规提醒再强调一次图像、文字、语音、人像相关素材必须确认授权企业内部知识库涉及敏感信息时要按角色做访问控制使用云端模型服务时确认数据的保密协议和输出内容归属。RAG 系统本质上是企业知识的分发中枢权限设计如果漏了检索接口可能变成数据泄露出口。上线前至少做一次安全测试重点覆盖越权访问和未授权文档检索。14. 总结与下一步NestJS Langchain.js 这套组合最适合的场景就是“用 TypeScript 技术栈做企业级 AI 全栈应用”。它把入口、文档处理、向量化、检索问答、批量任务、部署全部串在一条链路上相比纯 Python 方案前后端语言统一NestJS 的企业工程能力也让长期维护更可控。如果你准备动手第一阶段请优先验证三件事第一文档上传后能否成功完成切块和向量化入库第二中文文档的检索命中率是否达标第三问答接口是否稳定返回答案和来源。这三个点验证通过系统就已经具备内部使用的基础了。最容易踩的坑是切块参数和 Embedding 模型选型不要凭感觉设参数一定要建测试集对比效果。接下来可以继续扩展的方向包括引入 Agentic RAG让系统具备多步检索和工具调用能力结合知识图谱把实体关系与向量检索叠加处理复杂关联问题加入文档权限体系让不同部门只能检索自己的知识范围接入流式输出和前端引用高亮把问答体验做到产品级最后可以把系统接到企业微信、钉钉或飞书机器人上让知识库真正成为团队日常工具。建议先收藏这篇文章按流程跑通最小版本再根据业务反馈逐步迭代。 NestJS + Langchain.js 搭建企业级 RAG 知识库全栈指南
企业做 AI 知识库2025 年最主流的技术方案已经不是“把整份文档喂给大模型”而是 RAGRetrieval-Augmented Generation检索增强生成。这篇不铺垫背景直接拆解一个“NestJS Langchain.js 向量数据库”的 RAG 全栈知识库项目从工程目录设计、后端服务搭建、文档解析、文本切块、向量化入库到检索问答 API、前端接入、Docker 与宝塔部署、效果验证、问题排查完整走一遍。如果你正在做企业级后台管理系统、AI 客服、内部文档助手或者打算从前端/后端转 AI 全栈这篇文章可以直接按流程跟练。为什么选 NestJS Langchain.js 这套组合而不是 Python 后端核心原因是 TypeScript 全链路。NestJS 提供模块化、依赖注入、守卫、拦截器、生命周期管理等企业级后端能力Langchain.js 是 LangChain 的 TypeScript 实现提供文档加载器、文本切块器、Embedding 模型封装、向量库连接器、Prompt 模板和检索链。前后端和 AI 编排共用一套类型系统工程落地比“Node 前端 Python 后端”的双语言方案更顺也更容易在企业团队里维护。整个系统最核心的链路是文档上传 → 解析清洗 → 文本切块 → Embedding 向量化 → 写入向量数据库 → 用户提问 → 语义检索 TopK → 组装 Prompt → 大模型生成回答。下面我会把这条链路拆成工程实现给出可以复制改造的 NestJS 模块代码、Langchain.js 检索链代码、API 调用示例和部署配置。先看这个项目到底能做什么、门槛在哪里。1. 核心能力速览能力项说明项目类型AI 全栈应用 / 企业级 RAG 知识库问答系统后端框架NestJSNode.js TypeScript需 Node.js 18建议 20 LTSAI 编排框架Langchain.jsLangChain TypeScript 版本核心功能文档管理、文本解析、切块、向量化、语义检索、生成式问答、多轮会话典型组件PostgreSQL pgvector、Redis缓存/任务队列、MinIO文件存储、大模型 API模型接入方式OpenAI 兼容接口或本地模型服务通过环境变量切换前端方案可选 Next.js / Vue3也可先只做 RESTful API 简易管理页启动方式本地 npm 启动 / Docker Compose 一键编排是否支持 API支持提供文档上传、检索问答、会话历史等 RESTful 接口是否支持批量任务支持多文档可批量解析、切块、向量化入库配合 Redis 任务队列显存需求取决于所用的大模型和 Embedding 模型。调云端 API 无需本地 GPU本地部署模型需按模型量级评估适合场景企业内部知识库、客服问答、研发文档助手、产品文档检索、法律/合规文档复核从能力表可以看出这套方案不是拿一个大模型聊天那么简单。它的重点是把“文档怎么进、知识怎么存、问题怎么检索、答案怎么生成”做成一条标准流水线最后暴露成接口给前端或第三方系统调用。对企业来说RAG 的价值在于知识可以持续更新不依赖微调也不用把私有数据直接暴露给模型厂商。要注意的是显存占用和部署资源不能拍脑袋写死。如果底座模型调用云端 API后端只需要一台普通 2 核 4G 的云服务器如果要在本地跑 7B/13B 开源模型才需要考虑独立 GPU 机器。实际资源消耗取决于模型参数量、Embedding 模型、并发数和向量库规模建议先以最小配置跑通再逐步扩容。2. 适用场景与使用边界这类企业级 RAG 系统最适合解决三类问题第一企业内部文档太多且分散员工找不到答案第二客服或运营团队反复回答相似问题需要统一知识出口第三需要基于指定文档做审查、复核或内容生成例如产品说明书、操作手册、合同模板。通过接入 NestJS 的管理后台运营人员可以上传文档、查看入库状态、测试检索质量而不需要直接接触数据库和模型配置。这套系统也有明显的边界不要指望一个 RAG 项目解决所有 AI 问题。RAG 不会“无中生有地学会”文档里没有的知识检索不到的内容生成端照样会答错RAG 也不等于微调如果目标是让模型学习某种业务写法或风格应该考虑领域微调而不是只做知识库此外RAG 对文档质量很敏感扫描版 PDF、手写笔记、表格混排类文档直接解析入库的效果通常不理想。合规和授权问题必须放在前面说清楚。上传到知识库的文档务必确认内容来源合法拥有使用和分发的授权涉及客户隐私、内部财务、人员信息的文档要做权限分级接口层和文档层都要加访问控制如果使用云端大模型 API敏感数据是否可以被模型厂商处理需要提前确认企业安全合规要求。生产环境建议对知识库做“最小可见范围”设计而不是所有员工都能检索全部文档。3. 整体架构与工程目录设计一个可维护的企业级 RAG 项目建议拆成六层接入层前端/API 网关、应用层NestJS 业务模块、AI 编排层Langchain.js 链、数据层PostgreSQL、pgvector、Redis、MinIO、模型层大模型 API 或本地推理服务、基础设施层Docker、Nginx、日志监控。每一层职责单一后续替换模型或向量库时不会牵动整个系统。前端页面 / 管理后台 │ REST API / WebSocket ▼ NestJS 应用服务 ├── 用户与权限模块 ├── 文档管理模块 ├── 解析切块模块 ├── 向量化与检索模块 ├── 会话问答模块 └── 批量任务模块 │ ├── PostgreSQL pgvector业务数据 向量索引 ├── Redis缓存 / BullMQ 任务队列 ├── MinIO / 对象存储原始文档 └── 大模型 API / 本地模型服务Embedding ChatNestJS 的模块化在这里很合适。文档管理、知识库、会话、任务队列各自做成 Module每个 Module 内部再分 Controller、Service、Entity、DTO。实际工程可以按下面的目录组织src/ ├── modules/ │ ├── auth/ # 登录、鉴权、用户管理 │ ├── document/ # 文档上传、列表、删除 │ ├── knowledge/ # 知识库配置、切块参数 │ ├── ingestion/ # 解析、切块、向量化入库 │ ├── retrieval/ # 检索服务封装 │ ├── chat/ # 对话接口、会话历史 │ └── task/ # 批量任务队列 ├── common/ │ ├── filters/ # 全局异常过滤器 │ ├── interceptors/ # 日志、响应统一包装 │ └── guards/ # 权限守卫 ├── config/ # 环境变量、数据库配置 └── main.ts推荐用官方脚手架初始化 NestJS 工程后面所有模块都基于这个骨架扩展。NestJS 的依赖注入让模型客户端、向量库连接、配置中心可以被多个服务复用不会出现“每个模块各连一次模型”的重复代码。4. 环境准备与前置条件先列一份完整的环境清单。软件版本选择以稳定和团队熟悉度为优先没有绝对标准但下面的组合是目前企业项目里出现频率较高的。组件建议说明Node.js18 或 20 LTSNestJS 10/11 均支持20 LTS 更稳包管理器pnpm 或 npm团队统一即可PostgreSQL14 及以上需要支持 pgvector 扩展pgvector最新稳定版向量索引依赖Redis6.x / 7.xBullMQ 任务队列和会话缓存MinIO最新稳定版可选文件量大时使用大模型 APIOpenAI 兼容接口或本地服务需准备 API Key 和模型名称Docker20.10可选但推荐生产环境使用代码仓库Git配合 CI/CD 发布本地开发时可以先不装 MinIO文件存本地磁盘即可但 PostgreSQL 的 pgvector 扩展必须装好因为向量存储直接依赖它。验证 pgvector 是否可用执行CREATE EXTENSION IF NOT EXISTS vector; SELECT extversion FROM pg_extension WHERE extname vector;模型接入需要确认两件事Embedding 模型和对话模型。Embedding 负责把文本转成向量对话模型负责生成最终答案。生产环境可以直接用 OpenAI 兼容接口也可以接入国内厂商的兼容端点或者用 Ollama / vLLM 部署本地开源模型。项目里建议把模型配置全部放到.env这样切换模型不动代码。5. NestJS 后端工程搭建先用脚手架创建项目然后安装数据库和 Langchain.js 相关依赖。# 创建 NestJS 项目 nest new enterprise-rag-server --package-manager pnpm cd enterprise-rag-server # 数据库与配置 pnpm add nestjs/config nestjs/typeorm typeorm pg nestjs/platform-express # Langchain.js 核心与模型接入 pnpm add langchain langchain/core langchain/openai langchain/community langchain/textsplitters # 文档解析 pnpm add pdf-parse mammoth marked # 任务队列 pnpm add nestjs/bullmq bullmq安装完成后先配置全局模块。app.module.ts里引入 ConfigModule 和 TypeOrmModule数据库连接信息从环境变量读取// src/app.module.ts import { Module } from nestjs/common; import { ConfigModule, ConfigService } from nestjs/config; import { TypeOrmModule } from nestjs/typeorm; Module({ imports: [ ConfigModule.forRoot({ isGlobal: true }), TypeOrmModule.forRootAsync({ inject: [ConfigService], useFactory: (config: ConfigService) ({ type: postgres, host: config.get(DB_HOST, 127.0.0.1), port: config.getnumber(DB_PORT, 5432), username: config.get(DB_USER, postgres), password: config.get(DB_PASSWORD, postgres), database: config.get(DB_NAME, rag_kb), autoLoadEntities: true, synchronize: true, // 生产环境请改为 false使用 migration 管理 }), }), ], }) export class AppModule {}synchronize: true只适合开发环境因为频繁改动实体可能造成数据不一致。生产环境建议关闭用 TypeORM migration 管理表结构变更。文档模块是知识库的入口。实体设计上文档表和文本块表分开文档表保存文件元信息文本块表保存切块内容和向量。这样做的好处是删除文档时能级联清理向量数据检索时也能快速回溯到来源文档。// src/modules/document/entities/document.entity.ts import { Column, CreateDateColumn, Entity, PrimaryGeneratedColumn } from typeorm; Entity(documents) export class DocumentEntity { PrimaryGeneratedColumn(uuid) id: string; Column() title: string; Column({ default: pending }) status: string; // pending / processing / completed / failed Column({ nullable: true }) filePath: string; Column({ default: 0 }) chunkCount: number; CreateDateColumn() createdAt: Date; }文本块表需要额外存向量字段。pgvector 配合 TypeORM 时可以用vector类型但类型定义需要和 pgvector 类型对应。实际项目中通常写一个自定义类型映射或者在插入向量前用原生 SQL 设置类型。更简单的做法是业务元数据放在 TypeORM 实体向量字段通过 TypeORM 的query()或 Repository 的queryBuilder执行原生 SQL 写入避免类型映射问题。6. Langchain.js 与 RAG 核心链路实现RAG 的核心在 Langchain.js 的检索链。先创建模型客户端和 Embedding 客户端代码里统一走环境变量// src/common/ai/llm.provider.ts import { ChatOpenAI } from langchain/openai; import { OpenAIEmbeddings } from langchain/openai; export function createChatModel() { return new ChatOpenAI({ model: process.env.LLM_MODEL || gpt-4o-mini, apiKey: process.env.LLM_API_KEY, configuration: { baseURL: process.env.LLM_BASE_URL, // 兼容 OpenAI 的接口地址 }, temperature: 0.2, }); } export function createEmbeddings() { return new OpenAIEmbeddings({ model: process.env.EMBEDDING_MODEL || text-embedding-3-small, apiKey: process.env.EMBEDDING_API_KEY || process.env.LLM_API_KEY, configuration: { baseURL: process.env.EMBEDDING_BASE_URL, }, }); }这里用baseURL是为了兼容各类“OpenAI 协议”的模型服务包括国内厂商的兼容端点、Ollama 的 OpenAI 兼容接口、以及自建的 vLLM 服务。切换模型时只改.env不碰业务代码。检索问答链路推荐用 Langchain.js 的createRetrievalChain组装。先构造 Prompt 模板再创建“文档拼接链”最后把检索器接进来// src/modules/chat/rag.service.ts import { Injectable } from nestjs/common; import { ChatPromptTemplate } from langchain/core/prompts; import { createStuffDocumentsChain } from langchain/chains/combine_documents; import { createRetrievalChain } from langchain/chains/retrieval; import { createChatModel, createEmbeddings } from ../../common/ai/llm.provider; import { VectorStoreService } from ../retrieval/vector-store.service; Injectable() export class RagService { constructor(private readonly vectorStoreService: VectorStoreService) {} async buildChain() { const prompt ChatPromptTemplate.fromMessages([ [system, 你是一个企业知识库助手。请仅根据以下资料回答问题。如果资料中没有相关信息请直接说“资料中未找到相关内容”不要编造。\n\n资料\n{context}], [human, 问题{input}], ]); const combineDocsChain await createStuffDocumentsChain({ llm: createChatModel(), prompt, }); const retriever this.vectorStoreService.getVectorStore().asRetriever(8); return createRetrievalChain({ retriever, combineDocsChain, }); } async ask(question: string) { const chain await this.buildChain(); const response await chain.invoke({ input: question }); return response.answer; } }这段代码是 RAG 链路最短也最稳的写法。asRetriever(8)表示每次检索返回 8 个相关文本块temperature调低让模型更忠实于资料系统提示词里强制要求“没有资料就说没有”能明显减少幻觉。如果要做多轮会话可以在ask方法里先把用户问题做一次“改写”。常见做法是把历史对话和当前问题一起交给大模型让它生成一个完整上下文的新问题再拿这个问题去检索。这样做比直接把历史拼进 RAG 的检索输入更准确因为向量检索本身不擅长带上下文的模糊表达。7. 知识库处理解析、切块与向量化文档入库是整个 RAG 系统里最影响效果的一环。这部分的顺序是上传 → 解析 → 清洗 → 切块 → Embedding → 写入向量库。任何一个环节做不好检索质量都会明显下降。解析阶段不同文件类型走不同解析器。Markdown 可以直接读文本PDF 用pdf-parseWord 用mammoth把 docx 转成 HTML 或纯文本。要注意的是扫描版 PDF 没有文本层必须接 OCR常规解析方案处理不了。解析后要做基础清洗去掉页眉页脚、多余空行、无意义的超链接和表格乱码。切块策略是整个项目里最值得调优的参数。Langchain.js 的RecursiveCharacterTextSplitter是最常用的切块器它会按照分隔符优先级把文本切成块import { RecursiveCharacterTextSplitter } from langchain/textsplitters; const splitter new RecursiveCharacterTextSplitter({ chunkSize: 500, chunkOverlap: 80, separators: [\n\n, \n, 。, , , , , ], }); const chunks await splitter.splitText(cleanedText); console.log(切块数量${chunks.length});chunkSize和chunkOverlap要结合文档语言和 Embedding 模型的最大输入长度来调。中文文档建议chunkSize在 400 到 800 之间太小会导致上下文不完整太大则 Embedding 语义被稀释。chunkOverlap控制在 10% 到 20%让相邻块之间有重叠避免关键句子正好落在切分边界上。更进阶的方案是语义切块和“小到大检索”。语义切块利用 Embedding 判断文本主题变化在主题切换处切分小到大检索则是把小块用于检索命中后把更大范围的上下文一并交给大模型。这两种方案都值得在文档质量要求高的场景下尝试。向量化入库时如果用的是 pgvectorLangchain.js 的PGVectorStore可以直接把Document列表写入数据库// src/modules/retrieval/vector-store.service.ts import { Injectable } from nestjs/common; import { PGVectorStore } from langchain/community/vectorstores/pgvector; import { ConfigService } from nestjs/config; import { createEmbeddings } from ../../common/ai/llm.provider; Injectable() export class VectorStoreService { constructor(private readonly config: ConfigService) {} async getVectorStore() { return PGVectorStore.initialize(createEmbeddings(), { postgresConnectionOptions: { host: this.config.get(DB_HOST, 127.0.0.1), port: this.config.getnumber(DB_PORT, 5432), user: this.config.get(DB_USER, postgres), password: this.config.get(DB_PASSWORD, postgres), database: this.config.get(DB_NAME, rag_kb), }, tableName: document_embeddings, columns: { idColumnName: id, contentColumnName: content, metadataColumnName: metadata, vectorColumnName: embedding, }, }); } async addDocuments(documents: { pageContent: string; metadata: Recordstring, any }[]) { const store await this.getVectorStore(); await store.addDocuments(documents); } }入库前要检查 pgvector 查询性能。数据量小时无所谓数据量上来之后必须给向量列建索引。pgvector 支持 HNSW 和 IVFFlat 两种索引HNSW 查询精度更高、构建慢一些IVFFlat 构建快、查询快但参数需要调。生产环境推荐 HNSWCREATE INDEX ON document_embeddings USING hnsw (embedding vector_cosine_ops);批量任务用 BullMQ 来做。文档上传后NestJS 服务把“解析 切块 向量化”任务投递到 Redis 队列Worker 消费任务。这样有两个好处一是大批量文档不会阻塞 API 请求二是任务失败可以重试不会因为一条坏文档导致整个队列停住。任务状态可以记录在 documents 表里前端管理后台轮询即可。8. 检索问答 API 与批量任务后端对外暴露的接口建议分为三组文档管理接口、知识库处理接口、问答接口。下面是最小可用的接口设计方法路径说明POST/api/documents/upload上传文档GET/api/documents文档列表与状态DELETE/api/documents/:id删除文档及对应向量POST/api/documents/:id/process触发单文档入库POST/api/admin/batch-import批量导入目录或压缩包POST/api/chat/ask提问并获取回答GET/api/chat/history/:sessionId获取会话历史问答接口的请求和返回建议统一成 JSON方便前端和外部系统对接// POST /api/chat/ask { sessionId: abc-123, question: 企业知识库如何配置权限 }{ answer: 根据内部文档企业知识库的权限配置分为三步……, sources: [ { documentId: doc-001, title: 知识库运维手册, content: ……权限配置相关段落…… } ] }把sources来源引用返回给前端非常重要。企业场景里用户不仅要答案还要确认答案来自哪份文档。后续也可以做引用高亮点击来源直接跳转到原文位置。批量导入接口适合处理存量文档。常见做法是管理员把一批 PDF/DOCX/MD 放入某个目录或者上传 zip服务端遍历文件后逐个投递任务。批量任务的进度接口返回“总数、成功数、失败数、正在处理数”这样自然就实现了任务状态可视化。下面是一个 curl 调用批量任务的示例# 触发批量导入 curl -X POST http://127.0.0.1:3000/api/admin/batch-import \ -H Content-Type: application/json \ -H Authorization: Bearer token \ -d { sourceType: directory, sourcePath: /data/kb-docs, chunkSize: 500, chunkOverlap: 80 }Python 调用问答接口的示例也附上方便后续接到其他系统import requests url http://127.0.0.1:3000/api/chat/ask headers {Authorization: Bearer token, Content-Type: application/json} payload { sessionId: py-client-1, question: RAG 的切块参数应该怎么调 } resp requests.post(url, jsonpayload, timeout120) data resp.json() print(data[answer]) for source in data.get(sources, []): print(source[documentId], source[title])批量任务必须考虑失败重试策略。建议设置“失败后自动重试 2 次”并对解析失败的文件记录具体原因。如果是单个文件格式损坏跳过它比阻塞整批更重要如果是模型 API 限流等待时间补偿后重试效果更好。9. 前端接入与生产部署前端可以选择 Next.js、Vue3 Element Plus 或任意能调 REST API 的框架。需要实现的页面包括文档上传与状态页、知识库管理页、问答聊天页、系统配置页。聊天页建议使用 SSEServer-Sent Events或 WebSocket 实现流式输出体验远好于等完整响应。NestJS 返回 SSE 流很简单配合nestjs/platform-express和 Langchain.js 的stream方法即可。如果第一版只做 Web 端可以先不接流式直接返回完整 JSON等基础功能稳定后再优化交互体验。生产部署推荐 Docker Compose。下面是一个最小编排示例包含 NestJS 应用、PostgreSQL、Redis、MinIO 四个服务# docker-compose.yml version: 3.8 services: postgres: image: pgvector/pgvector:pg16 container_name: rag-postgres environment: POSTGRES_DB: rag_kb POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres ports: - 5432:5432 volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 5s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: rag-redis ports: - 6379:6379 minio: image: minio/minio:latest container_name: rag-minio command: server /data --console-address :9001 environment: MINIO_ROOT_USER: minioadmin MINIO_ROOT_PASSWORD: minioadmin ports: - 9000:9000 - 9001:9001 volumes: - miniodata:/data rag-server: build: context: . dockerfile: Dockerfile container_name: rag-server ports: - 3000:3000 env_file: - .env depends_on: postgres: condition: service_healthy redis: condition: service_started restart: unless-stopped volumes: pgdata: miniodata:很多同学问“宝塔支持部署 NestJS 项目吗”答案是支持。宝塔里有两种方式一种是直接用“Node.js 项目”功能选择 Node 版本、入口文件和后端端口加上 Supervisor 守护进程另一种更推荐就是上面这种 Docker Compose 方式宝塔面板可以通过 Docker 管理器安装 Compose 服务点击编排即可启动整套环境。两种方式都需要在宝塔的防火墙和安全组里放行对应端口。部署时还要注意 Nginx 反向代理。前端页面走 80/443/api路径代理到 3000 端口WebSocket 或 SSE 需要额外配置proxy_http_version 1.1、proxy_set_header Connection等参数。HTTPS 证书用免费证书即可接口层再配合 JWT 鉴权避免服务直接暴露在公网。10. 功能测试与效果验证系统跑通之后最怕的是“接口都通但回答质量没法验收”。建议从四个维度做测试基础流程、检索质量、生成质量、稳定性。基础流程测试覆盖完整链路上传一篇 PDF → 等待状态变为 completed → 提问文档相关内容 → 返回答案并带来源文档。这个过程建议用脚本自动跑而不是每次都靠页面点。下面是判断成功的标准文档状态从 pending → processing → completedchunkCount 大于 0。问题能命中文档内容答案包含来源文档。文档删除后再检索相同问题不再返回该文档内容。检索质量测试要建立一份测试集。准备 20 到 50 个真实问题每个问题标注“应该命中的文档或段落”然后跑检索统计命中率。命中率低于 60% 时优先调切块参数和检索 TopK而不是换大模型。这个测试集很关键之后每次调整 Embedding 模型、切块策略、向量索引都用同一份测试集对比效果好坏一目了然。生成质量测试关注三件事答案是否忠于资料、是否回答了问题、是否出现幻觉。建议把问题和对应答案整理成表格由业务人员人工打分分“准确、部分准确、错误、无中生有”四档。对“无中生有”的回答要重点排查是检索没召回相关内容还是 Prompt 约束不够或者模型本身幻觉严重。从工程经验看大部分幻觉问题都是检索召回不佳造成的优先修检索链路。稳定性测试可以用并发请求验证。比如用脚本同时发起 20 个问答请求观察接口响应时间和服务内存。问答接口如果依赖外部模型 API建议加上超时控制和熔断降级模型 API 超时时直接返回“服务繁忙请稍后重试”而不是让用户一直转圈。11. 资源占用与性能观察RAG 系统的性能瓶颈通常不在应用本身而在三个地方模型 API 的响应延迟、向量检索的耗时、文档解析的 CPU 占用。先看延迟链路。一次问答请求的时间大致是Embedding 检索几十到几百毫秒 大模型生成根据模型和输出长度几秒到几十秒。如果用户体感慢优先看是不是模型生成太慢而不是急着加服务器配置。可以在 NestJS 里给/api/chat/ask加日志记录检索耗时和生成耗时分别多少[chat] 检索耗时: 210ms [chat] 生成耗时: 5.8s [chat] 总耗时: 6.1s这样能快速定位瓶颈。检索耗时长检查 pgvector 索引是否生效以及是否把全表扫描跑成了线性查询生成耗时长检查模型选择、输出长度、并发限流。内存占用方面Node.js 服务的堆内存可以通过process.memoryUsage()监控容器部署用docker stats观察。向量检索本身不占太多应用内存因为向量在 PostgreSQL 里但如果用了本地 Embedding 模型模型加载后的内存和显存占用就不能忽略。实际占用需以本机测试为准不同模型差异很大。降低资源占用的常用手段包括Embedding 结果加缓存相同或相似文本不重复向量化检索 TopK 不要盲目调大8 到 10 通常够用批量入库任务控制并发数避免同时解析大量文档导致 CPU 打满PostgreSQL 开启连接池限制防止应用实例多了之后把数据库连接耗尽。12. 常见问题与排查方法问题现象可能原因排查方式解决方案pgvector 扩展无法创建数据库版本过低或未安装插件执行SELECT version();检查 PG 版本使用 pgvector/pgvector 镜像重建数据库检索返回空结果向量库里没有数据或 Embedding 维度不匹配查询 document_embeddings 表是否有记录检查入库任务状态和切块结果中文切块效果差分隔符没有包含中文标点打印切块结果观察断句位置在 separators 里补充“。”等分隔符问答接口超时模型 API 响应慢或网络不稳定查看日志中的生成耗时调大超时时间接入流式输出Docker 中应用连不上数据库连接地址写成 127.0.0.1检查 compose 网络和环境变量容器内改用服务名 postgres 访问宝塔部署后页面 502Nginx 没配代理或服务未启动检查 Nginx 错误日志正确配置 proxy_pass 到 3000 端口模型 API 提示限流请求并发过高查看模型服务返回码加入队列限流和退避重试文档状态一直 processing任务队列消费失败查看 BullMQ worker 日志修复解析异常设置失败重试补一个容易被忽略的问题Embedding 模型切换后向量维度变了但旧数据还在库里会导致查询报错。切换 Embedding 模型时必须清空旧向量数据或重建一份新的向量表不要混用不同模型的向量。建议在建表时把 Embedding 模型名称作为元数据保存查询时带上模型条件避免脏数据干扰检索。另一个高频问题是“为什么答案没有引用我上传的新文档”。多数情况是切块后的向量已经入库但检索的 TopK 结果里相关度排名不够或者新文档和旧知识内容重叠被旧文档挤掉了。解决思路是把新文档的 metadata 加上时间戳和权重字段检索时把时间权重纳入排序或者直接做一个“指定文档 ID 范围检索”的功能管理员可以先锁定期望的文档范围做验证。13. 最佳实践与合规提醒工程上建议先跑通最小闭环再逐步扩展。第一版只需要一个上传接口、一个切块入库流程、一个问答接口、一个简单管理页面。确认链路稳定后再补权限、批量任务、流式输出、监控告警。不要一上来就设计十几个微服务企业内部系统的核心是稳定不是技术炫酷。代码和配置层面环境变量必须隔离。模型 API Key、数据库密码、Redis 密码统一放.env并加入.gitignore。.env.example保留一份模板方便同事快速配置本地环境。生产环境用 Docker 容器时密钥通过环境变量注入不要写死在镜像里。文档管理上建议为每份文档保存状态和版本。企业知识库不是一次性上传就结束文档会被修订、删除、过期。给文档加 version 字段入库时记录文件 hash内容变化时自动触发重新解析这样才能保证用户检索到的不是陈旧内容。批量任务要写日志落库记录每批任务的开始时间、结束时间、成功数和失败原因方便追溯。合规提醒再强调一次图像、文字、语音、人像相关素材必须确认授权企业内部知识库涉及敏感信息时要按角色做访问控制使用云端模型服务时确认数据的保密协议和输出内容归属。RAG 系统本质上是企业知识的分发中枢权限设计如果漏了检索接口可能变成数据泄露出口。上线前至少做一次安全测试重点覆盖越权访问和未授权文档检索。14. 总结与下一步NestJS Langchain.js 这套组合最适合的场景就是“用 TypeScript 技术栈做企业级 AI 全栈应用”。它把入口、文档处理、向量化、检索问答、批量任务、部署全部串在一条链路上相比纯 Python 方案前后端语言统一NestJS 的企业工程能力也让长期维护更可控。如果你准备动手第一阶段请优先验证三件事第一文档上传后能否成功完成切块和向量化入库第二中文文档的检索命中率是否达标第三问答接口是否稳定返回答案和来源。这三个点验证通过系统就已经具备内部使用的基础了。最容易踩的坑是切块参数和 Embedding 模型选型不要凭感觉设参数一定要建测试集对比效果。接下来可以继续扩展的方向包括引入 Agentic RAG让系统具备多步检索和工具调用能力结合知识图谱把实体关系与向量检索叠加处理复杂关联问题加入文档权限体系让不同部门只能检索自己的知识范围接入流式输出和前端引用高亮把问答体验做到产品级最后可以把系统接到企业微信、钉钉或飞书机器人上让知识库真正成为团队日常工具。建议先收藏这篇文章按流程跑通最小版本再根据业务反馈逐步迭代。