1. 项目概述为什么是 NestJS LangChain最近在折腾一个AI应用想把大模型的能力真正集成到业务系统里而不是简单地调个API就完事。踩了一圈坑之后我发现很多教程都在讲LangChain怎么用但很少有人聊清楚怎么把它放到一个正经的、能长期维护的后端项目里。结果就是Demo跑得飞起一上生产就各种头疼代码耦合严重、配置满天飞、监控和日志无从下手、扩展新功能像在拆炸弹。这让我意识到架构的缺失是很多AI应用从“玩具”迈向“产品”的最大障碍。于是我决定用NestJS和LangChain的组合来趟一条路。NestJS一个基于TypeScript的渐进式Node.js框架以其清晰的分层架构、强大的依赖注入和模块化设计闻名是构建企业级后端服务的利器。而LangChain则是当前连接大模型与外部数据、工具的最主流框架之一。把它们俩结合目标很明确用NestJS的工程化能力为LangChain的AI逻辑提供一个稳固、可测试、易扩展的“家”。这不仅仅是技术栈的叠加更是一种开发范式的转变——让AI能力像数据库服务、消息队列一样成为你应用架构中一个规整、可控的组成部分。2. 核心架构设计分层与解耦直接在一个Controller里写满LangChain的调用代码是最快的但也是“死”得最快的。为了长期可维护性我们必须进行清晰的分层。2.1 领域驱动下的模块划分我倾向于采用一种改良的领域驱动设计DDD思想来组织代码但不是完全照搬其复杂的战术模式。核心是按业务能力Bounded Context划分模块而不是按技术层级。假设我们在构建一个“智能客服助手”系统它需要处理用户查询、检索知识库、调用工具如查订单并生成回答。我们的模块结构可能如下src/ ├── modules/ │ ├── ai-engine/ # AI引擎核心模块 │ │ ├── chains/ # 存放各种LangChain链 │ │ ├── agents/ # 存放智能体Agent逻辑 │ │ ├── tools/ # 自定义工具Tool定义 │ │ ├── prompts/ # 提示词模板管理 │ │ ├── memories/ # 对话记忆管理 │ │ ├── ai-engine.module.ts │ │ └── ai-engine.service.ts # 对外暴露的统一AI服务接口 │ ├── knowledge-base/ # 知识库管理模块独立领域 │ ├── conversation/ # 会话管理模块独立领域 │ └── user/ # 用户管理模块 ├── common/ # 公共资源管道、过滤器、守卫、装饰器等 └── config/ # 配置文件为什么这么分ai-engine模块是AI能力的集散地所有与LangChain直接相关的代码——链、代理、工具、提示词——都收敛在这里。它对外提供一个干净的Service接口如AiEngineService。其他业务模块如conversation不需要知道LangChain的具体实现只需调用这个接口。业务模块保持纯粹conversation模块只关心会话的创建、存储和流转逻辑。当它需要生成一个回复时它调用AiEngineService并传递必要的上下文如用户历史、知识库片段。这符合单一职责原则。tools的归属是关键决策点一个工具比如“查询用户订单”它既包含AI调用逻辑LangChain Tool也包含业务数据操作。我强烈建议将工具的实现放在其所属的业务模块如order模块然后在ai-engine模块中注册或引用它。这避免了ai-engine模块变成上帝模块过度耦合所有业务逻辑。2.2 依赖注入与配置管理NestJS的依赖注入容器是管理复杂依赖关系的利器。对于LangChain我们需要注入的主要是两类对象模型实例和链/代理实例。1. 模型实例的提供与配置不要在代码里硬编码API Key和Base URL。利用NestJS的ConfigModule和自定义Provider。// ai-engine/providers/model.providers.ts import { Provider } from nestjs/common; import { ConfigService } from nestjs/config; import { ChatOpenAI } from langchain/openai; import { ChatOllama } from langchain/ollama; export const modelProviders: Provider[] [ { provide: ChatOpenAI, // 使用字符串或自定义Token作为标识 useFactory: (configService: ConfigService) { return new ChatOpenAI({ apiKey: configService.get(OPENAI_API_KEY), modelName: configService.get(OPENAI_MODEL, gpt-4o-mini), temperature: 0.1, // ... 其他配置可以从configService读取 }); }, inject: [ConfigService], }, { provide: ChatOllama, useFactory: (configService: ConfigService) { return new ChatOllama({ baseUrl: configService.get(OLLAMA_BASE_URL, http://localhost:11434), model: configService.get(OLLAMA_MODEL, llama3.2), }); }, inject: [ConfigService], }, ];然后在AiEngineModule中导入这些Providers。这样我们可以在不同的链中根据需要注入不同的模型。注意对于生产环境强烈建议将模型配置如modelName,temperature也放到环境变量或配置中心。这样可以在不重启服务的情况下动态切换模型或调整参数进行A/B测试或快速回滚。2. 链/代理的构建与提供链和代理的构建逻辑可能比较复杂涉及多个工具的组装、提示词的加载。我们可以为每个主要的链或代理创建一个独立的Provider。// ai-engine/providers/chain.providers.ts import { Provider } from nestjs/common; import { ChatOpenAI } from langchain/openai; import { createRetrieverTool } from langchain/tools/retriever; import { createReactAgent } from langchain/agents; import { ConversationSummaryBufferMemory } from langchain/memory; export const customerSupportAgentProvider: Provider { provide: CUSTOMER_SUPPORT_AGENT, useFactory: async ( chatModel: ChatOpenAI, orderTool: any, // 假设从OrderModule注入的工具 knowledgeRetrieverTool: any, // 知识库检索工具 memory: ConversationSummaryBufferMemory, ) { // 1. 组装工具列表 const tools [orderTool, knowledgeRetrieverTool]; // 2. 创建Agent执行器 const agentExecutor await createReactAgent({ llm: chatModel, tools, memory, // 注入记忆使Agent有上下文 // prompt: 可以在这里传入自定义的提示词 }); return agentExecutor; }, inject: [ChatOpenAI, ORDER_TOOL, KNOWLEDGE_RETRIEVER_TOOL, CONVERSATION_MEMORY], };这种做法的好处是依赖清晰工厂函数明确声明了构建Agent所需的所有依赖。可测试我们可以轻松地为useFactory函数编写单元测试或者通过NestJS的测试工具模拟依赖。懒加载与复用NestJS会管理这些Provider的生命周期通常是单例避免了重复构建的开销。2.3 服务层统一的AI能力门面AiEngineService是这个模块对外的唯一出口。它不应该包含具体的链构建逻辑而是一个路由和协调器。// ai-engine/ai-engine.service.ts import { Injectable, Inject } from nestjs/common; Injectable() export class AiEngineService { constructor( Inject(CUSTOMER_SUPPORT_AGENT) private readonly customerSupportAgent: AgentExecutor, Inject(SIMPLE_QA_CHAIN) private readonly qaChain: RunnableSequence, // 假设一个简单的问答链 ) {} async handleCustomerQuery(sessionId: string, userInput: string, context?: any) { // 1. 可能根据sessionId加载特定记忆 // 2. 准备输入可能合并上下文 const input { input: userInput, chat_history: context?.history, external_context: context?.knowledge, }; // 3. 调用具体的Agent const result await this.customerSupportAgent.invoke(input); // 4. 处理结果可能包括解析、格式化、记录日志等 return this.formatAgentResponse(result); } async simpleQA(question: string) { // 调用简单的问答链用于不需要复杂交互的场景 return this.qaChain.invoke({ question }); } private formatAgentResponse(rawResult: any) { // 标准化输出格式便于前端处理 return { answer: rawResult.output, sourceDocuments: rawResult.sourceDocuments || [], usedTools: rawResult.intermediateSteps?.map(step step.action.tool) || [], }; } }这个服务层起到了关键的抽象作用它隔离了外部模块与LangChain内部实现的复杂性。如果未来我们把LangChain换成另一个框架或者彻底重写了某个链的逻辑只要AiEngineService的接口不变其他业务模块就完全感知不到。3. 核心细节解析与实操要点有了顶层设计我们来看看几个关键组件的实现细节和容易踩坑的地方。3.1 提示词工程从字符串到可管理资产把提示词硬编码在代码里是灾难的开始。随着迭代提示词会频繁修改硬编码导致需要重新部署。更糟的是多行模板字符串在代码中极难阅读和维护。解决方案外部化与模块化。1. 使用模板文件将提示词保存在独立的.txt或.md文件中。LangChain的PromptTemplate支持从文件加载。// prompts/customer-support-system.prompt.md 你是一个专业的客服助手负责回答用户关于产品的问题。 请根据以下上下文信息来回答问题。如果你不知道答案就如实说不知道不要编造。 上下文信息 {context} 用户问题{question} 请用友好、专业的语气回答// ai-engine/prompts/prompt-registry.service.ts import { readFileSync } from fs; import { join } from path; import { PromptTemplate } from langchain/core/prompts; Injectable() export class PromptRegistryService { private promptCache new Mapstring, PromptTemplate(); getPromptTemplate(name: string): PromptTemplate { if (this.promptCache.has(name)) { return this.promptCache.get(name); } const filePath join(__dirname, assets, prompts, ${name}.prompt.md); const templateStr readFileSync(filePath, utf-8); const prompt PromptTemplate.fromTemplate(templateStr); this.promptCache.set(name, prompt); return prompt; } }2. 支持动态变量与条件逻辑复杂的提示词可能需要根据用户身份、时间等因素动态变化。我们可以创建更高级的提示词组装器。async buildDynamicPrompt(userTier: string): PromisePromptTemplate { let basePrompt this.getPromptTemplate(customer-support-base); let toneInstruction ; if (userTier vip) { toneInstruction 请使用格外尊贵和体贴的语气。; } else if (userTier new) { toneInstruction 请用简单、清晰的语言解释避免使用专业术语。; } // 这里可以更复杂比如从数据库读取针对该用户的特定指令 const finalTemplate await basePrompt.partial({ tone_instruction: toneInstruction, current_date: new Date().toISOString().split(T)[0], }); return finalTemplate; }3. 版本管理与A/B测试在生产环境中可以对提示词进行版本化管理如存数据库或配置中心并配合特性开关Feature Flag进行A/B测试量化不同提示词对业务指标的影响。3.2 工具Tools的设计与集成工具是LangChain Agent与外界交互的桥梁。设计不当的工具会成为系统的瓶颈。1. 工具的实现原则单一职责一个工具只做一件事。比如GetUserOrderTool只负责查询订单不要在里面又发邮件又更新数据库。健壮性工具内部必须有完善的错误处理。网络超时、数据库异常、参数无效等情况都要有明确的错误信息返回给Agent而不是抛出未捕获的异常导致整个链崩溃。输入验证与类型安全利用TypeScript和Zod等库在工具入口处严格验证输入参数。// order/tools/get-user-order.tool.ts import { Tool } from langchain/core/tools; import { z } from zod; import { OrderService } from ../order.service; // 业务服务 const inputSchema z.object({ orderId: z.string().min(1, 订单ID不能为空), }); export class GetUserOrderTool extends Tool { name get_user_order; description 根据订单ID查询用户的订单详情包括状态、商品和物流信息。; schema inputSchema; constructor(private readonly orderService: OrderService) { super(); } protected async _call(arg: string): Promisestring { let parsedInput; try { // 1. 解析并验证输入 const args JSON.parse(arg); parsedInput inputSchema.parse(args); } catch (error) { return 输入参数解析失败${error.message}。请提供格式正确的JSON例如{orderId: ORD123456}; } try { // 2. 调用业务服务 const order await this.orderService.findById(parsedInput.orderId); if (!order) { return 未找到订单ID为 ${parsedInput.orderId} 的订单。; } // 3. 格式化输出便于Agent理解 return JSON.stringify({ status: order.status, items: order.items.map(i ${i.name} x ${i.quantity}), shippingAddress: order.shippingAddress, estimatedDelivery: order.estimatedDelivery, }); } catch (error) { // 4. 业务逻辑错误处理 console.error(查询订单失败:, error); return 系统内部错误暂时无法查询订单详情。; } } }2. 工具的依赖注入与注册工具类本身是一个普通的NestJS Provider它依赖业务层的Service。我们需要在模块中提供它并可能将其“注册”到AI引擎的上下文中。// order/order.module.ts import { Module } from nestjs/common; import { OrderService } from ./order.service; import { GetUserOrderTool } from ./tools/get-user-order.tool; Module({ providers: [OrderService, GetUserOrderTool], exports: [OrderService, GetUserOrderTool], // 导出工具供AiEngineModule使用 }) export class OrderModule {}// ai-engine/ai-engine.module.ts import { Module } from nestjs/common; import { OrderModule } from ../order/order.module; import { AiEngineService } from ./ai-engine.service; import { customerSupportAgentProvider } from ./providers/chain.providers; Module({ imports: [OrderModule], // 导入OrderModule以获取其导出的工具 providers: [ AiEngineService, customerSupportAgentProvider, // 这个Provider会注入ORDER_TOOL // 我们需要一个Provider来将GetUserOrderTool实例映射到ORDER_TOOL这个Token { provide: ORDER_TOOL, useExisting: GetUserOrderTool, // 使用useExisting引用已存在的Provider实例 }, ], exports: [AiEngineService], }) export class AiEngineModule {}实操心得工具描述的“艺术”Agent完全依赖工具的name和description来决定何时调用哪个工具。description的撰写至关重要必须清晰、无歧义准确描述工具的功能、输入和输出。包含示例在描述中暗示输入格式如“输入应为包含orderId字段的JSON字符串”。使用Agent能理解的语言避免内部术语用自然语言描述。好的描述能显著提升Agent调用工具的准确率。3.3 记忆Memory管理状态化的对话对于多轮对话应用记忆是核心。LangChain提供了多种记忆类型如ConversationBufferMemory,ConversationSummaryMemory,ConversationBufferWindowMemory等。1. 记忆的存储与会话隔离在Web服务中记忆必须与会话Session或用户绑定。我们不能把不同用户的对话历史混在一起。// ai-engine/memories/memory.service.ts import { Injectable } from nestjs/common; import { ConversationSummaryBufferMemory } from langchain/memory; import { RedisChatMessageHistory } from langchain/redis; import { ConfigService } from nestjs/config; Injectable() export class MemoryService { private memoryStore new Mapstring, ConversationSummaryBufferMemory(); constructor(private configService: ConfigService) {} async getMemoryForSession(sessionId: string): PromiseConversationSummaryBufferMemory { if (this.memoryStore.has(sessionId)) { return this.memoryStore.get(sessionId); } // 使用Redis作为持久化存储避免服务重启丢失记忆 const chatHistory new RedisChatMessageHistory({ sessionId, config: { url: this.configService.get(REDIS_URL), }, }); const memory new ConversationSummaryBufferMemory({ memoryKey: chat_history, chatHistory: chatHistory, llm: new ChatOpenAI({ modelName: gpt-3.5-turbo }), // 用一个便宜的模型做总结 maxTokenLimit: 1000, // 控制记忆的token长度 returnMessages: true, }); this.memoryStore.set(sessionId, memory); return memory; } async clearMemory(sessionId: string) { const memory this.memoryStore.get(sessionId); if (memory) { await memory.clear(); this.memoryStore.delete(sessionId); } } }2. 记忆的注入与使用在构建Agent时将特定会话的记忆实例注入进去。// 在某个Service或Provider工厂中 const sessionMemory await this.memoryService.getMemoryForSession(sessionId); const agentExecutor await createReactAgent({ llm: chatModel, tools, memory: sessionMemory, // 注入带有历史记录的memory });3. 记忆策略的选择ConversationBufferMemory保存所有历史记录简单但可能很快超出上下文窗口。ConversationSummaryMemory用另一个LLM总结历史对话节省token但可能丢失细节且增加延迟和成本。ConversationBufferWindowMemory只保留最近K轮对话是平衡细节和长度的常用选择。ConversationSummaryBufferMemory如上例结合了总结和最近对话缓冲是比较理想的方案。踩坑记录记忆的序列化直接尝试将LangChain的Memory对象存入Redis或数据库会遇到序列化问题。一定要使用LangChain官方提供的*ChatMessageHistory类如RedisChatMessageHistory,PostgresChatMessageHistory它们已经处理好了消息的序列化和存储逻辑。4. 实操过程与核心环节实现让我们通过一个完整的流程看看如何将上述设计落地实现一个“用户查询订单物流”的智能客服场景。4.1 环境准备与依赖安装首先创建一个新的NestJS项目并安装核心依赖。# 创建NestJS项目 nest new my-ai-assistant --package-manager npm cd my-ai-assistant # 安装LangChain相关核心包 npm install langchain/core langchain/openai langchain/community # 安装LangChain与NestJS社区集成包如果有 # npm install langchain/nestjs (注此为示例需确认是否存在) # 安装工具可能需要的依赖如Redis、Zod npm install ioredis zod npm install -D types/ioredis # 安装配置管理依赖 npm install nestjs/config4.2 构建业务模块与工具1. 订单模块与工具创建订单模块并实现查询订单的工具。// src/modules/order/order.service.ts import { Injectable } from nestjs/common; export interface Order { id: string; userId: string; status: pending | shipped | delivered | cancelled; items: Array{ name: string; quantity: number }; shippingAddress: string; estimatedDelivery: string; } Injectable() export class OrderService { private orders: Order[] []; // 模拟数据实际应接数据库 async findById(orderId: string): PromiseOrder | null { return this.orders.find(order order.id orderId) || null; } }// src/modules/order/tools/get-user-order.tool.ts // (代码见上文3.2节此处省略)// src/modules/order/order.module.ts import { Module } from nestjs/common; import { OrderService } from ./order.service; import { GetUserOrderTool } from ./tools/get-user-order.tool; Module({ providers: [OrderService, GetUserOrderTool], exports: [OrderService, GetUserOrderTool], }) export class OrderModule {}2. 知识库模块与检索工具假设我们有一个简单的向量知识库。// src/modules/knowledge-base/knowledge-base.service.ts import { Injectable } from nestjs/common; import { MemoryVectorStore } from langchain/vectorstores/memory; import { OpenAIEmbeddings } from langchain/openai; import { Document } from langchain/core/documents; Injectable() export class KnowledgeBaseService { private vectorStore: MemoryVectorStore; async init() { const embeddings new OpenAIEmbeddings(); const docs [ new Document({ pageContent: 我们的退货政策是30天内无条件退货。, metadata: { source: policy } }), new Document({ pageContent: 标准配送需要3-5个工作日。, metadata: { source: shipping } }), ]; this.vectorStore await MemoryVectorStore.fromDocuments(docs, embeddings); } async search(query: string, k 2): PromiseDocument[] { if (!this.vectorStore) await this.init(); return this.vectorStore.similaritySearch(query, k); } }// src/modules/knowledge-base/tools/search-knowledge.tool.ts import { Tool } from langchain/core/tools; import { KnowledgeBaseService } from ../knowledge-base.service; export class SearchKnowledgeTool extends Tool { name search_knowledge_base; description 在公司知识库中搜索与用户问题相关的信息。输入应为纯文本的搜索查询。; constructor(private readonly knowledgeBaseService: KnowledgeBaseService) { super(); } protected async _call(input: string): Promisestring { try { const docs await this.knowledgeBaseService.search(input); if (docs.length 0) { return 在知识库中未找到相关信息。; } // 将检索到的文档内容合并成字符串返回 return docs.map(doc doc.pageContent).join(\n---\n); } catch (error) { return 搜索知识库时出错${error.message}; } } }4.3 装配AI引擎1. 配置模块与模型Provider// src/modules/ai-engine/ai-engine.module.ts import { Module } from nestjs/common; import { ConfigModule } from nestjs/config; import { OrderModule } from ../order/order.module; import { KnowledgeBaseModule } from ../knowledge-base/knowledge-base.module; import { AiEngineService } from ./ai-engine.service; import { PromptRegistryService } from ./prompts/prompt-registry.service; import { MemoryService } from ./memories/memory.service; import { modelProviders } from ./providers/model.providers; import { customerSupportAgentProvider } from ./providers/chain.providers; Module({ imports: [ConfigModule.forRoot(), OrderModule, KnowledgeBaseModule], // 导入业务模块 providers: [ AiEngineService, PromptRegistryService, MemoryService, ...modelProviders, customerSupportAgentProvider, // 提供工具Token的映射 { provide: ORDER_TOOL, useExisting: GetUserOrderTool, }, { provide: KNOWLEDGE_RETRIEVER_TOOL, useExisting: SearchKnowledgeTool, }, { provide: CONVERSATION_MEMORY, useFactory: (memoryService: MemoryService) { // 注意这里返回的是一个工厂函数因为记忆是会话级别的。 // 实际注入时需要在调用处动态获取。 return (sessionId: string) memoryService.getMemoryForSession(sessionId); }, inject: [MemoryService], }, ], exports: [AiEngineService], // 只导出Service }) export class AiEngineModule {}2. 实现AI引擎服务服务需要能够处理会话并动态地为每个会话创建带有正确记忆的Agent。// src/modules/ai-engine/ai-engine.service.ts import { Injectable, Inject, OnModuleInit } from nestjs/common; import { ChatOpenAI } from langchain/openai; import { createReactAgent } from langchain/agents; import { AiEngineService } from ./ai-engine.service; import { MemoryService } from ./memories/memory.service; import { PromptRegistryService } from ./prompts/prompt-registry.service; Injectable() export class AiEngineService implements OnModuleInit { private baseAgentExecutor: any; // 一个不包含记忆的基础Agent蓝图 constructor( Inject(ChatOpenAI) private readonly chatModel: ChatOpenAI, Inject(ORDER_TOOL) private readonly orderTool: any, Inject(KNOWLEDGE_RETRIEVER_TOOL) private readonly knowledgeTool: any, private readonly memoryService: MemoryService, private readonly promptService: PromptRegistryService, ) {} async onModuleInit() { // 初始化一个不包含记忆的基础Agent配置后续为每个会话复制并添加记忆 // 注意LangChain的createReactAgent可能返回一个Runnable具体用法需参考最新文档 // 这里假设它能接受一个配置对象并返回一个可执行器 const tools [this.orderTool, this.knowledgeTool]; const prompt await this.promptService.getPromptTemplate(customer-support-agent); // 此处简化实际构建可能更复杂 this.baseAgentExecutor { llm: this.chatModel, tools, prompt }; } async handleSessionQuery(sessionId: string, userInput: string): Promisestring { // 1. 获取该会话的记忆 const memory await this.memoryService.getMemoryForSession(sessionId); // 2. 加载或构建带有当前记忆的Agent // 注意LangChain的Agent执行器构建可能需要根据具体版本调整 // 一种常见模式是使用RunnableWithMessageHistory来包装链并注入记忆 const agentWithMemory await createReactAgent({ ...this.baseAgentExecutor, memory, // 注入会话特定记忆 }); // 3. 准备输入记忆系统会自动处理chat_history const input { input: userInput }; // 4. 调用Agent const response await agentWithMemory.invoke(input); // 5. 返回结果 return response.output; } }4.4 创建API入口最后创建一个Controller来暴露API。// src/modules/conversation/conversation.controller.ts import { Controller, Post, Body, Session } from nestjs/common; import { AiEngineService } from ../ai-engine/ai-engine.service; Controller(conversation) export class ConversationController { constructor(private readonly aiEngineService: AiEngineService) {} Post(message) async handleMessage( Body() body: { sessionId?: string; message: string }, Session() session: Recordstring, any, // 如果使用session中间件 ) { // 优先使用body中的sessionId否则使用HTTP session ID const sessionId body.sessionId || session.id; if (!sessionId) { throw new Error(无法确定会话ID); } const aiResponse await this.aiEngineService.handleSessionQuery(sessionId, body.message); return { sessionId, response: aiResponse, timestamp: new Date().toISOString(), }; } }5. 常见问题与排查技巧实录在实际开发和部署中你一定会遇到各种问题。以下是我踩过的一些坑和解决方案。5.1 Agent陷入循环或调用错误工具现象Agent反复调用同一个工具或者在不该调用工具的时候调用导致对话卡死或结果荒谬。排查与解决检查工具描述这是最常见的原因。确保description清晰、准确并包含输入格式的暗示。用自然语言描述“在什么情况下使用我”。优化提示词System Prompt在给Agent的System Prompt中明确约束其行为。例如“你只能使用提供的工具。如果用户的问题与工具功能无关请直接回答你不知道不要尝试调用工具。”“在决定使用工具前先简要思考一下用户的意图是否与工具描述匹配。”启用详细日志在创建Agent时设置verbose: true这样可以在控制台看到Agent的完整思考过程Chain of Thought这对于调试其决策逻辑至关重要。使用maxIterations参数在创建Agent执行器时设置maxIterations例如15防止因逻辑错误导致无限循环。考虑使用更稳定的Agent类型ReActAgent灵活但可能不稳定。对于确定性高的任务可以考虑使用Plan-and-Execute模式的Agent或者直接使用预定义的链Chain。5.2 性能问题响应慢Token消耗高现象API响应时间过长或者调用成本急剧上升。优化策略流式输出Streaming对于生成时间较长的回答使用LangChain的流式响应接口将已生成的部分实时返回给前端提升用户体验。NestJS可以很好地支持Server-Sent Events (SSE) 或 WebSocket。缓存提示词缓存如我们之前做的将解析后的PromptTemplate缓存起来。向量检索缓存对相同的查询缓存向量检索的结果。可以使用RedisCache包装你的向量存储检索方法。工具结果缓存对于幂等的、不常变化的工具调用如查询静态知识可以缓存其结果。控制上下文长度使用有窗口或总结的记忆避免ConversationBufferMemory无限制增长。精简输入在将外部数据如检索到的文档放入上下文前尝试进行摘要或提取最相关的片段。选择合适模型在保证效果的前提下使用更小、更快的模型如gpt-4o-mini相比gpt-4。异步与并行如果Agent需要调用多个独立的工具可以探索让它们并行执行注意LangChain默认是顺序执行。这需要对执行流程有更精细的控制。5.3 错误处理与系统韧性目标不让一次失败的AI调用导致整个API请求崩溃。最佳实践全局异常过滤器在NestJS中创建全局异常过滤器捕获LangChain调用中抛出的未处理异常并返回结构化的错误信息给客户端而不是500 Internal Server Error。为工具调用添加超时使用Promise.race或AbortController为每个工具调用设置超时如10秒防止某个慢速工具拖垮整个请求。实现降级策略主备模型当主要模型如OpenAI不可用时自动降级到备用模型如本地Ollama。简化流程当复杂Agent失败时可以回退到一个简单的提示词问答链。静态回复在最坏情况下返回预设的友好错误消息。全面的日志记录记录每一次AI调用的详细信息会话ID、用户输入、使用的工具、模型响应、Token用量、耗时、是否出错。这些日志是监控、调试和成本分析的生命线。可以使用NestJS的Logger并集成到像ELK这样的日志系统中。5.4 监控与可观测性在微服务架构下AI服务作为一个独立组件必须有完善的可观测性。关键指标Metrics请求量 延迟总请求数、成功率、平均/百分位响应时间。Token消耗区分输入Token和输出Token按模型、按接口统计。工具调用统计每个工具被调用的次数、平均耗时、失败率。Agent迭代次数分布情况用于发现异常循环。分布式追踪Tracing在一次用户请求中如果涉及调用AI服务、数据库、外部API使用OpenTelemetry等工具将这些调用串联起来形成一个完整的追踪链路便于定位性能瓶颈。健康检查为AI服务提供健康检查端点/health检查其对底层模型API如OpenAI的连接性、向量数据库的连接性等。6. 进阶思考从链Chain到图Graph随着业务逻辑复杂化单一的链或Agent可能不够用。LangChain最近力推的LangGraph提供了一个更强大的范式来编排复杂的、有状态的AI工作流。LangChain vs LangGraph的核心区别LangChain (Chain)可以看作是一个线性的、预定义好步骤的管道。数据从一端流入经过一系列固定的处理LLM调用、工具调用从另一端流出。适合流程确定的任务。LangGraph基于图论允许你定义节点Nodes和边Edges构建一个有状态的工作流图。执行引擎可以根据当前状态和条件边决定下一个执行哪个节点支持循环、分支、并行等复杂逻辑。它本质上是为构建复杂的、多步骤的**智能体Agent**而设计的。何时考虑使用LangGraph当你的AI应用需要多轮次、多分支的决策时例如一个客服场景先理解问题可能需要查知识库可能需要调用工具可能需要反问用户澄清所有这些步骤不是固定的顺序。当你需要更精细地控制状态State在整个工作流中的流转和修改时。当你需要实现类似多智能体协作的模式时。在NestJS中集成LangGraph 集成思路与集成LangChain链类似。你可以将整个Graph定义封装成一个NestJS Provider。Graph的State可以映射到你的业务上下文和会话记忆上。NestJS的模块化特性使得为不同的复杂业务流程创建不同的Graph变得非常清晰。构建可维护的AI应用架构其核心思想从未改变关注点分离、依赖注入、面向接口编程、完善的错误处理与监控。NestJS为我们提供了实践这些理念的优秀框架而LangChain及LangGraph则提供了实现AI逻辑的强大工具箱。将它们结合不是简单地把两个库堆在一起而是用工程化的思维去驾驭AI能力让AI真正可靠、可控地服务于业务。这条路还在快速演进但以稳固的架构为基础我们就能更从容地应对变化。 NestJS与LangChain集成：构建可维护的企业级AI应用架构
1. 项目概述为什么是 NestJS LangChain最近在折腾一个AI应用想把大模型的能力真正集成到业务系统里而不是简单地调个API就完事。踩了一圈坑之后我发现很多教程都在讲LangChain怎么用但很少有人聊清楚怎么把它放到一个正经的、能长期维护的后端项目里。结果就是Demo跑得飞起一上生产就各种头疼代码耦合严重、配置满天飞、监控和日志无从下手、扩展新功能像在拆炸弹。这让我意识到架构的缺失是很多AI应用从“玩具”迈向“产品”的最大障碍。于是我决定用NestJS和LangChain的组合来趟一条路。NestJS一个基于TypeScript的渐进式Node.js框架以其清晰的分层架构、强大的依赖注入和模块化设计闻名是构建企业级后端服务的利器。而LangChain则是当前连接大模型与外部数据、工具的最主流框架之一。把它们俩结合目标很明确用NestJS的工程化能力为LangChain的AI逻辑提供一个稳固、可测试、易扩展的“家”。这不仅仅是技术栈的叠加更是一种开发范式的转变——让AI能力像数据库服务、消息队列一样成为你应用架构中一个规整、可控的组成部分。2. 核心架构设计分层与解耦直接在一个Controller里写满LangChain的调用代码是最快的但也是“死”得最快的。为了长期可维护性我们必须进行清晰的分层。2.1 领域驱动下的模块划分我倾向于采用一种改良的领域驱动设计DDD思想来组织代码但不是完全照搬其复杂的战术模式。核心是按业务能力Bounded Context划分模块而不是按技术层级。假设我们在构建一个“智能客服助手”系统它需要处理用户查询、检索知识库、调用工具如查订单并生成回答。我们的模块结构可能如下src/ ├── modules/ │ ├── ai-engine/ # AI引擎核心模块 │ │ ├── chains/ # 存放各种LangChain链 │ │ ├── agents/ # 存放智能体Agent逻辑 │ │ ├── tools/ # 自定义工具Tool定义 │ │ ├── prompts/ # 提示词模板管理 │ │ ├── memories/ # 对话记忆管理 │ │ ├── ai-engine.module.ts │ │ └── ai-engine.service.ts # 对外暴露的统一AI服务接口 │ ├── knowledge-base/ # 知识库管理模块独立领域 │ ├── conversation/ # 会话管理模块独立领域 │ └── user/ # 用户管理模块 ├── common/ # 公共资源管道、过滤器、守卫、装饰器等 └── config/ # 配置文件为什么这么分ai-engine模块是AI能力的集散地所有与LangChain直接相关的代码——链、代理、工具、提示词——都收敛在这里。它对外提供一个干净的Service接口如AiEngineService。其他业务模块如conversation不需要知道LangChain的具体实现只需调用这个接口。业务模块保持纯粹conversation模块只关心会话的创建、存储和流转逻辑。当它需要生成一个回复时它调用AiEngineService并传递必要的上下文如用户历史、知识库片段。这符合单一职责原则。tools的归属是关键决策点一个工具比如“查询用户订单”它既包含AI调用逻辑LangChain Tool也包含业务数据操作。我强烈建议将工具的实现放在其所属的业务模块如order模块然后在ai-engine模块中注册或引用它。这避免了ai-engine模块变成上帝模块过度耦合所有业务逻辑。2.2 依赖注入与配置管理NestJS的依赖注入容器是管理复杂依赖关系的利器。对于LangChain我们需要注入的主要是两类对象模型实例和链/代理实例。1. 模型实例的提供与配置不要在代码里硬编码API Key和Base URL。利用NestJS的ConfigModule和自定义Provider。// ai-engine/providers/model.providers.ts import { Provider } from nestjs/common; import { ConfigService } from nestjs/config; import { ChatOpenAI } from langchain/openai; import { ChatOllama } from langchain/ollama; export const modelProviders: Provider[] [ { provide: ChatOpenAI, // 使用字符串或自定义Token作为标识 useFactory: (configService: ConfigService) { return new ChatOpenAI({ apiKey: configService.get(OPENAI_API_KEY), modelName: configService.get(OPENAI_MODEL, gpt-4o-mini), temperature: 0.1, // ... 其他配置可以从configService读取 }); }, inject: [ConfigService], }, { provide: ChatOllama, useFactory: (configService: ConfigService) { return new ChatOllama({ baseUrl: configService.get(OLLAMA_BASE_URL, http://localhost:11434), model: configService.get(OLLAMA_MODEL, llama3.2), }); }, inject: [ConfigService], }, ];然后在AiEngineModule中导入这些Providers。这样我们可以在不同的链中根据需要注入不同的模型。注意对于生产环境强烈建议将模型配置如modelName,temperature也放到环境变量或配置中心。这样可以在不重启服务的情况下动态切换模型或调整参数进行A/B测试或快速回滚。2. 链/代理的构建与提供链和代理的构建逻辑可能比较复杂涉及多个工具的组装、提示词的加载。我们可以为每个主要的链或代理创建一个独立的Provider。// ai-engine/providers/chain.providers.ts import { Provider } from nestjs/common; import { ChatOpenAI } from langchain/openai; import { createRetrieverTool } from langchain/tools/retriever; import { createReactAgent } from langchain/agents; import { ConversationSummaryBufferMemory } from langchain/memory; export const customerSupportAgentProvider: Provider { provide: CUSTOMER_SUPPORT_AGENT, useFactory: async ( chatModel: ChatOpenAI, orderTool: any, // 假设从OrderModule注入的工具 knowledgeRetrieverTool: any, // 知识库检索工具 memory: ConversationSummaryBufferMemory, ) { // 1. 组装工具列表 const tools [orderTool, knowledgeRetrieverTool]; // 2. 创建Agent执行器 const agentExecutor await createReactAgent({ llm: chatModel, tools, memory, // 注入记忆使Agent有上下文 // prompt: 可以在这里传入自定义的提示词 }); return agentExecutor; }, inject: [ChatOpenAI, ORDER_TOOL, KNOWLEDGE_RETRIEVER_TOOL, CONVERSATION_MEMORY], };这种做法的好处是依赖清晰工厂函数明确声明了构建Agent所需的所有依赖。可测试我们可以轻松地为useFactory函数编写单元测试或者通过NestJS的测试工具模拟依赖。懒加载与复用NestJS会管理这些Provider的生命周期通常是单例避免了重复构建的开销。2.3 服务层统一的AI能力门面AiEngineService是这个模块对外的唯一出口。它不应该包含具体的链构建逻辑而是一个路由和协调器。// ai-engine/ai-engine.service.ts import { Injectable, Inject } from nestjs/common; Injectable() export class AiEngineService { constructor( Inject(CUSTOMER_SUPPORT_AGENT) private readonly customerSupportAgent: AgentExecutor, Inject(SIMPLE_QA_CHAIN) private readonly qaChain: RunnableSequence, // 假设一个简单的问答链 ) {} async handleCustomerQuery(sessionId: string, userInput: string, context?: any) { // 1. 可能根据sessionId加载特定记忆 // 2. 准备输入可能合并上下文 const input { input: userInput, chat_history: context?.history, external_context: context?.knowledge, }; // 3. 调用具体的Agent const result await this.customerSupportAgent.invoke(input); // 4. 处理结果可能包括解析、格式化、记录日志等 return this.formatAgentResponse(result); } async simpleQA(question: string) { // 调用简单的问答链用于不需要复杂交互的场景 return this.qaChain.invoke({ question }); } private formatAgentResponse(rawResult: any) { // 标准化输出格式便于前端处理 return { answer: rawResult.output, sourceDocuments: rawResult.sourceDocuments || [], usedTools: rawResult.intermediateSteps?.map(step step.action.tool) || [], }; } }这个服务层起到了关键的抽象作用它隔离了外部模块与LangChain内部实现的复杂性。如果未来我们把LangChain换成另一个框架或者彻底重写了某个链的逻辑只要AiEngineService的接口不变其他业务模块就完全感知不到。3. 核心细节解析与实操要点有了顶层设计我们来看看几个关键组件的实现细节和容易踩坑的地方。3.1 提示词工程从字符串到可管理资产把提示词硬编码在代码里是灾难的开始。随着迭代提示词会频繁修改硬编码导致需要重新部署。更糟的是多行模板字符串在代码中极难阅读和维护。解决方案外部化与模块化。1. 使用模板文件将提示词保存在独立的.txt或.md文件中。LangChain的PromptTemplate支持从文件加载。// prompts/customer-support-system.prompt.md 你是一个专业的客服助手负责回答用户关于产品的问题。 请根据以下上下文信息来回答问题。如果你不知道答案就如实说不知道不要编造。 上下文信息 {context} 用户问题{question} 请用友好、专业的语气回答// ai-engine/prompts/prompt-registry.service.ts import { readFileSync } from fs; import { join } from path; import { PromptTemplate } from langchain/core/prompts; Injectable() export class PromptRegistryService { private promptCache new Mapstring, PromptTemplate(); getPromptTemplate(name: string): PromptTemplate { if (this.promptCache.has(name)) { return this.promptCache.get(name); } const filePath join(__dirname, assets, prompts, ${name}.prompt.md); const templateStr readFileSync(filePath, utf-8); const prompt PromptTemplate.fromTemplate(templateStr); this.promptCache.set(name, prompt); return prompt; } }2. 支持动态变量与条件逻辑复杂的提示词可能需要根据用户身份、时间等因素动态变化。我们可以创建更高级的提示词组装器。async buildDynamicPrompt(userTier: string): PromisePromptTemplate { let basePrompt this.getPromptTemplate(customer-support-base); let toneInstruction ; if (userTier vip) { toneInstruction 请使用格外尊贵和体贴的语气。; } else if (userTier new) { toneInstruction 请用简单、清晰的语言解释避免使用专业术语。; } // 这里可以更复杂比如从数据库读取针对该用户的特定指令 const finalTemplate await basePrompt.partial({ tone_instruction: toneInstruction, current_date: new Date().toISOString().split(T)[0], }); return finalTemplate; }3. 版本管理与A/B测试在生产环境中可以对提示词进行版本化管理如存数据库或配置中心并配合特性开关Feature Flag进行A/B测试量化不同提示词对业务指标的影响。3.2 工具Tools的设计与集成工具是LangChain Agent与外界交互的桥梁。设计不当的工具会成为系统的瓶颈。1. 工具的实现原则单一职责一个工具只做一件事。比如GetUserOrderTool只负责查询订单不要在里面又发邮件又更新数据库。健壮性工具内部必须有完善的错误处理。网络超时、数据库异常、参数无效等情况都要有明确的错误信息返回给Agent而不是抛出未捕获的异常导致整个链崩溃。输入验证与类型安全利用TypeScript和Zod等库在工具入口处严格验证输入参数。// order/tools/get-user-order.tool.ts import { Tool } from langchain/core/tools; import { z } from zod; import { OrderService } from ../order.service; // 业务服务 const inputSchema z.object({ orderId: z.string().min(1, 订单ID不能为空), }); export class GetUserOrderTool extends Tool { name get_user_order; description 根据订单ID查询用户的订单详情包括状态、商品和物流信息。; schema inputSchema; constructor(private readonly orderService: OrderService) { super(); } protected async _call(arg: string): Promisestring { let parsedInput; try { // 1. 解析并验证输入 const args JSON.parse(arg); parsedInput inputSchema.parse(args); } catch (error) { return 输入参数解析失败${error.message}。请提供格式正确的JSON例如{orderId: ORD123456}; } try { // 2. 调用业务服务 const order await this.orderService.findById(parsedInput.orderId); if (!order) { return 未找到订单ID为 ${parsedInput.orderId} 的订单。; } // 3. 格式化输出便于Agent理解 return JSON.stringify({ status: order.status, items: order.items.map(i ${i.name} x ${i.quantity}), shippingAddress: order.shippingAddress, estimatedDelivery: order.estimatedDelivery, }); } catch (error) { // 4. 业务逻辑错误处理 console.error(查询订单失败:, error); return 系统内部错误暂时无法查询订单详情。; } } }2. 工具的依赖注入与注册工具类本身是一个普通的NestJS Provider它依赖业务层的Service。我们需要在模块中提供它并可能将其“注册”到AI引擎的上下文中。// order/order.module.ts import { Module } from nestjs/common; import { OrderService } from ./order.service; import { GetUserOrderTool } from ./tools/get-user-order.tool; Module({ providers: [OrderService, GetUserOrderTool], exports: [OrderService, GetUserOrderTool], // 导出工具供AiEngineModule使用 }) export class OrderModule {}// ai-engine/ai-engine.module.ts import { Module } from nestjs/common; import { OrderModule } from ../order/order.module; import { AiEngineService } from ./ai-engine.service; import { customerSupportAgentProvider } from ./providers/chain.providers; Module({ imports: [OrderModule], // 导入OrderModule以获取其导出的工具 providers: [ AiEngineService, customerSupportAgentProvider, // 这个Provider会注入ORDER_TOOL // 我们需要一个Provider来将GetUserOrderTool实例映射到ORDER_TOOL这个Token { provide: ORDER_TOOL, useExisting: GetUserOrderTool, // 使用useExisting引用已存在的Provider实例 }, ], exports: [AiEngineService], }) export class AiEngineModule {}实操心得工具描述的“艺术”Agent完全依赖工具的name和description来决定何时调用哪个工具。description的撰写至关重要必须清晰、无歧义准确描述工具的功能、输入和输出。包含示例在描述中暗示输入格式如“输入应为包含orderId字段的JSON字符串”。使用Agent能理解的语言避免内部术语用自然语言描述。好的描述能显著提升Agent调用工具的准确率。3.3 记忆Memory管理状态化的对话对于多轮对话应用记忆是核心。LangChain提供了多种记忆类型如ConversationBufferMemory,ConversationSummaryMemory,ConversationBufferWindowMemory等。1. 记忆的存储与会话隔离在Web服务中记忆必须与会话Session或用户绑定。我们不能把不同用户的对话历史混在一起。// ai-engine/memories/memory.service.ts import { Injectable } from nestjs/common; import { ConversationSummaryBufferMemory } from langchain/memory; import { RedisChatMessageHistory } from langchain/redis; import { ConfigService } from nestjs/config; Injectable() export class MemoryService { private memoryStore new Mapstring, ConversationSummaryBufferMemory(); constructor(private configService: ConfigService) {} async getMemoryForSession(sessionId: string): PromiseConversationSummaryBufferMemory { if (this.memoryStore.has(sessionId)) { return this.memoryStore.get(sessionId); } // 使用Redis作为持久化存储避免服务重启丢失记忆 const chatHistory new RedisChatMessageHistory({ sessionId, config: { url: this.configService.get(REDIS_URL), }, }); const memory new ConversationSummaryBufferMemory({ memoryKey: chat_history, chatHistory: chatHistory, llm: new ChatOpenAI({ modelName: gpt-3.5-turbo }), // 用一个便宜的模型做总结 maxTokenLimit: 1000, // 控制记忆的token长度 returnMessages: true, }); this.memoryStore.set(sessionId, memory); return memory; } async clearMemory(sessionId: string) { const memory this.memoryStore.get(sessionId); if (memory) { await memory.clear(); this.memoryStore.delete(sessionId); } } }2. 记忆的注入与使用在构建Agent时将特定会话的记忆实例注入进去。// 在某个Service或Provider工厂中 const sessionMemory await this.memoryService.getMemoryForSession(sessionId); const agentExecutor await createReactAgent({ llm: chatModel, tools, memory: sessionMemory, // 注入带有历史记录的memory });3. 记忆策略的选择ConversationBufferMemory保存所有历史记录简单但可能很快超出上下文窗口。ConversationSummaryMemory用另一个LLM总结历史对话节省token但可能丢失细节且增加延迟和成本。ConversationBufferWindowMemory只保留最近K轮对话是平衡细节和长度的常用选择。ConversationSummaryBufferMemory如上例结合了总结和最近对话缓冲是比较理想的方案。踩坑记录记忆的序列化直接尝试将LangChain的Memory对象存入Redis或数据库会遇到序列化问题。一定要使用LangChain官方提供的*ChatMessageHistory类如RedisChatMessageHistory,PostgresChatMessageHistory它们已经处理好了消息的序列化和存储逻辑。4. 实操过程与核心环节实现让我们通过一个完整的流程看看如何将上述设计落地实现一个“用户查询订单物流”的智能客服场景。4.1 环境准备与依赖安装首先创建一个新的NestJS项目并安装核心依赖。# 创建NestJS项目 nest new my-ai-assistant --package-manager npm cd my-ai-assistant # 安装LangChain相关核心包 npm install langchain/core langchain/openai langchain/community # 安装LangChain与NestJS社区集成包如果有 # npm install langchain/nestjs (注此为示例需确认是否存在) # 安装工具可能需要的依赖如Redis、Zod npm install ioredis zod npm install -D types/ioredis # 安装配置管理依赖 npm install nestjs/config4.2 构建业务模块与工具1. 订单模块与工具创建订单模块并实现查询订单的工具。// src/modules/order/order.service.ts import { Injectable } from nestjs/common; export interface Order { id: string; userId: string; status: pending | shipped | delivered | cancelled; items: Array{ name: string; quantity: number }; shippingAddress: string; estimatedDelivery: string; } Injectable() export class OrderService { private orders: Order[] []; // 模拟数据实际应接数据库 async findById(orderId: string): PromiseOrder | null { return this.orders.find(order order.id orderId) || null; } }// src/modules/order/tools/get-user-order.tool.ts // (代码见上文3.2节此处省略)// src/modules/order/order.module.ts import { Module } from nestjs/common; import { OrderService } from ./order.service; import { GetUserOrderTool } from ./tools/get-user-order.tool; Module({ providers: [OrderService, GetUserOrderTool], exports: [OrderService, GetUserOrderTool], }) export class OrderModule {}2. 知识库模块与检索工具假设我们有一个简单的向量知识库。// src/modules/knowledge-base/knowledge-base.service.ts import { Injectable } from nestjs/common; import { MemoryVectorStore } from langchain/vectorstores/memory; import { OpenAIEmbeddings } from langchain/openai; import { Document } from langchain/core/documents; Injectable() export class KnowledgeBaseService { private vectorStore: MemoryVectorStore; async init() { const embeddings new OpenAIEmbeddings(); const docs [ new Document({ pageContent: 我们的退货政策是30天内无条件退货。, metadata: { source: policy } }), new Document({ pageContent: 标准配送需要3-5个工作日。, metadata: { source: shipping } }), ]; this.vectorStore await MemoryVectorStore.fromDocuments(docs, embeddings); } async search(query: string, k 2): PromiseDocument[] { if (!this.vectorStore) await this.init(); return this.vectorStore.similaritySearch(query, k); } }// src/modules/knowledge-base/tools/search-knowledge.tool.ts import { Tool } from langchain/core/tools; import { KnowledgeBaseService } from ../knowledge-base.service; export class SearchKnowledgeTool extends Tool { name search_knowledge_base; description 在公司知识库中搜索与用户问题相关的信息。输入应为纯文本的搜索查询。; constructor(private readonly knowledgeBaseService: KnowledgeBaseService) { super(); } protected async _call(input: string): Promisestring { try { const docs await this.knowledgeBaseService.search(input); if (docs.length 0) { return 在知识库中未找到相关信息。; } // 将检索到的文档内容合并成字符串返回 return docs.map(doc doc.pageContent).join(\n---\n); } catch (error) { return 搜索知识库时出错${error.message}; } } }4.3 装配AI引擎1. 配置模块与模型Provider// src/modules/ai-engine/ai-engine.module.ts import { Module } from nestjs/common; import { ConfigModule } from nestjs/config; import { OrderModule } from ../order/order.module; import { KnowledgeBaseModule } from ../knowledge-base/knowledge-base.module; import { AiEngineService } from ./ai-engine.service; import { PromptRegistryService } from ./prompts/prompt-registry.service; import { MemoryService } from ./memories/memory.service; import { modelProviders } from ./providers/model.providers; import { customerSupportAgentProvider } from ./providers/chain.providers; Module({ imports: [ConfigModule.forRoot(), OrderModule, KnowledgeBaseModule], // 导入业务模块 providers: [ AiEngineService, PromptRegistryService, MemoryService, ...modelProviders, customerSupportAgentProvider, // 提供工具Token的映射 { provide: ORDER_TOOL, useExisting: GetUserOrderTool, }, { provide: KNOWLEDGE_RETRIEVER_TOOL, useExisting: SearchKnowledgeTool, }, { provide: CONVERSATION_MEMORY, useFactory: (memoryService: MemoryService) { // 注意这里返回的是一个工厂函数因为记忆是会话级别的。 // 实际注入时需要在调用处动态获取。 return (sessionId: string) memoryService.getMemoryForSession(sessionId); }, inject: [MemoryService], }, ], exports: [AiEngineService], // 只导出Service }) export class AiEngineModule {}2. 实现AI引擎服务服务需要能够处理会话并动态地为每个会话创建带有正确记忆的Agent。// src/modules/ai-engine/ai-engine.service.ts import { Injectable, Inject, OnModuleInit } from nestjs/common; import { ChatOpenAI } from langchain/openai; import { createReactAgent } from langchain/agents; import { AiEngineService } from ./ai-engine.service; import { MemoryService } from ./memories/memory.service; import { PromptRegistryService } from ./prompts/prompt-registry.service; Injectable() export class AiEngineService implements OnModuleInit { private baseAgentExecutor: any; // 一个不包含记忆的基础Agent蓝图 constructor( Inject(ChatOpenAI) private readonly chatModel: ChatOpenAI, Inject(ORDER_TOOL) private readonly orderTool: any, Inject(KNOWLEDGE_RETRIEVER_TOOL) private readonly knowledgeTool: any, private readonly memoryService: MemoryService, private readonly promptService: PromptRegistryService, ) {} async onModuleInit() { // 初始化一个不包含记忆的基础Agent配置后续为每个会话复制并添加记忆 // 注意LangChain的createReactAgent可能返回一个Runnable具体用法需参考最新文档 // 这里假设它能接受一个配置对象并返回一个可执行器 const tools [this.orderTool, this.knowledgeTool]; const prompt await this.promptService.getPromptTemplate(customer-support-agent); // 此处简化实际构建可能更复杂 this.baseAgentExecutor { llm: this.chatModel, tools, prompt }; } async handleSessionQuery(sessionId: string, userInput: string): Promisestring { // 1. 获取该会话的记忆 const memory await this.memoryService.getMemoryForSession(sessionId); // 2. 加载或构建带有当前记忆的Agent // 注意LangChain的Agent执行器构建可能需要根据具体版本调整 // 一种常见模式是使用RunnableWithMessageHistory来包装链并注入记忆 const agentWithMemory await createReactAgent({ ...this.baseAgentExecutor, memory, // 注入会话特定记忆 }); // 3. 准备输入记忆系统会自动处理chat_history const input { input: userInput }; // 4. 调用Agent const response await agentWithMemory.invoke(input); // 5. 返回结果 return response.output; } }4.4 创建API入口最后创建一个Controller来暴露API。// src/modules/conversation/conversation.controller.ts import { Controller, Post, Body, Session } from nestjs/common; import { AiEngineService } from ../ai-engine/ai-engine.service; Controller(conversation) export class ConversationController { constructor(private readonly aiEngineService: AiEngineService) {} Post(message) async handleMessage( Body() body: { sessionId?: string; message: string }, Session() session: Recordstring, any, // 如果使用session中间件 ) { // 优先使用body中的sessionId否则使用HTTP session ID const sessionId body.sessionId || session.id; if (!sessionId) { throw new Error(无法确定会话ID); } const aiResponse await this.aiEngineService.handleSessionQuery(sessionId, body.message); return { sessionId, response: aiResponse, timestamp: new Date().toISOString(), }; } }5. 常见问题与排查技巧实录在实际开发和部署中你一定会遇到各种问题。以下是我踩过的一些坑和解决方案。5.1 Agent陷入循环或调用错误工具现象Agent反复调用同一个工具或者在不该调用工具的时候调用导致对话卡死或结果荒谬。排查与解决检查工具描述这是最常见的原因。确保description清晰、准确并包含输入格式的暗示。用自然语言描述“在什么情况下使用我”。优化提示词System Prompt在给Agent的System Prompt中明确约束其行为。例如“你只能使用提供的工具。如果用户的问题与工具功能无关请直接回答你不知道不要尝试调用工具。”“在决定使用工具前先简要思考一下用户的意图是否与工具描述匹配。”启用详细日志在创建Agent时设置verbose: true这样可以在控制台看到Agent的完整思考过程Chain of Thought这对于调试其决策逻辑至关重要。使用maxIterations参数在创建Agent执行器时设置maxIterations例如15防止因逻辑错误导致无限循环。考虑使用更稳定的Agent类型ReActAgent灵活但可能不稳定。对于确定性高的任务可以考虑使用Plan-and-Execute模式的Agent或者直接使用预定义的链Chain。5.2 性能问题响应慢Token消耗高现象API响应时间过长或者调用成本急剧上升。优化策略流式输出Streaming对于生成时间较长的回答使用LangChain的流式响应接口将已生成的部分实时返回给前端提升用户体验。NestJS可以很好地支持Server-Sent Events (SSE) 或 WebSocket。缓存提示词缓存如我们之前做的将解析后的PromptTemplate缓存起来。向量检索缓存对相同的查询缓存向量检索的结果。可以使用RedisCache包装你的向量存储检索方法。工具结果缓存对于幂等的、不常变化的工具调用如查询静态知识可以缓存其结果。控制上下文长度使用有窗口或总结的记忆避免ConversationBufferMemory无限制增长。精简输入在将外部数据如检索到的文档放入上下文前尝试进行摘要或提取最相关的片段。选择合适模型在保证效果的前提下使用更小、更快的模型如gpt-4o-mini相比gpt-4。异步与并行如果Agent需要调用多个独立的工具可以探索让它们并行执行注意LangChain默认是顺序执行。这需要对执行流程有更精细的控制。5.3 错误处理与系统韧性目标不让一次失败的AI调用导致整个API请求崩溃。最佳实践全局异常过滤器在NestJS中创建全局异常过滤器捕获LangChain调用中抛出的未处理异常并返回结构化的错误信息给客户端而不是500 Internal Server Error。为工具调用添加超时使用Promise.race或AbortController为每个工具调用设置超时如10秒防止某个慢速工具拖垮整个请求。实现降级策略主备模型当主要模型如OpenAI不可用时自动降级到备用模型如本地Ollama。简化流程当复杂Agent失败时可以回退到一个简单的提示词问答链。静态回复在最坏情况下返回预设的友好错误消息。全面的日志记录记录每一次AI调用的详细信息会话ID、用户输入、使用的工具、模型响应、Token用量、耗时、是否出错。这些日志是监控、调试和成本分析的生命线。可以使用NestJS的Logger并集成到像ELK这样的日志系统中。5.4 监控与可观测性在微服务架构下AI服务作为一个独立组件必须有完善的可观测性。关键指标Metrics请求量 延迟总请求数、成功率、平均/百分位响应时间。Token消耗区分输入Token和输出Token按模型、按接口统计。工具调用统计每个工具被调用的次数、平均耗时、失败率。Agent迭代次数分布情况用于发现异常循环。分布式追踪Tracing在一次用户请求中如果涉及调用AI服务、数据库、外部API使用OpenTelemetry等工具将这些调用串联起来形成一个完整的追踪链路便于定位性能瓶颈。健康检查为AI服务提供健康检查端点/health检查其对底层模型API如OpenAI的连接性、向量数据库的连接性等。6. 进阶思考从链Chain到图Graph随着业务逻辑复杂化单一的链或Agent可能不够用。LangChain最近力推的LangGraph提供了一个更强大的范式来编排复杂的、有状态的AI工作流。LangChain vs LangGraph的核心区别LangChain (Chain)可以看作是一个线性的、预定义好步骤的管道。数据从一端流入经过一系列固定的处理LLM调用、工具调用从另一端流出。适合流程确定的任务。LangGraph基于图论允许你定义节点Nodes和边Edges构建一个有状态的工作流图。执行引擎可以根据当前状态和条件边决定下一个执行哪个节点支持循环、分支、并行等复杂逻辑。它本质上是为构建复杂的、多步骤的**智能体Agent**而设计的。何时考虑使用LangGraph当你的AI应用需要多轮次、多分支的决策时例如一个客服场景先理解问题可能需要查知识库可能需要调用工具可能需要反问用户澄清所有这些步骤不是固定的顺序。当你需要更精细地控制状态State在整个工作流中的流转和修改时。当你需要实现类似多智能体协作的模式时。在NestJS中集成LangGraph 集成思路与集成LangChain链类似。你可以将整个Graph定义封装成一个NestJS Provider。Graph的State可以映射到你的业务上下文和会话记忆上。NestJS的模块化特性使得为不同的复杂业务流程创建不同的Graph变得非常清晰。构建可维护的AI应用架构其核心思想从未改变关注点分离、依赖注入、面向接口编程、完善的错误处理与监控。NestJS为我们提供了实践这些理念的优秀框架而LangChain及LangGraph则提供了实现AI逻辑的强大工具箱。将它们结合不是简单地把两个库堆在一起而是用工程化的思维去驾驭AI能力让AI真正可靠、可控地服务于业务。这条路还在快速演进但以稳固的架构为基础我们就能更从容地应对变化。