LangChain.js 完全开发手册（十一）企业级 AI 应用架构设计

鲫小鱼
337 阅读8分钟

第11章：企业级 AI 应用架构设计

前言

大家好，我是鲫小鱼。是一名不写前端代码的前端工程师，热衷于分享非前端的知识，带领切图仔逃离切图圈子，欢迎关注我，微信公众号：《鲫小鱼不正经》。欢迎点赞、收藏、关注，一键三连！！

🎯 本章学习目标

  • 理解企业级 AI 应用的整体架构版图：前端、服务层、数据层、模型层、观测与治理
  • 掌握多环境配置、租户与权限、数据治理、可观测性与稳定性保障
  • 设计支持 RAG、Agent、任务编排（LangGraph）的可扩展架构与接口规范
  • 搭建高可用、高性能、可灰度、可审计的生产就绪系统
  • 提供 Next.js + Node + 向量数据库 + 消息队列的参考实现与最佳实践

🧭 架构全景

11.1 企业级 AI 应用参考架构

┌───────────┐      ┌───────────────────┐      ┌────────────────┐
│  前端 Web │─────▶│   API Gateway/ BFF │─────▶│  应用服务层     │
│  Next.js  │◀─────│(Auth/Rate/Cache)  │◀─────│(RAG/Agent/Graph)│
└───────────┘      └───────────────────┘      └────────────────┘
                                           ┌─────────────┐  ┌────────────┐
                                           │ 向量数据库   │  │ 关系型数据库│
                                           │ Chroma/Pine │  │ Postgres   │
                                           └─────────────┘  └────────────┘
                                           ┌─────────────┐  ┌────────────┐
                                           │ 消息队列     │  │ 对象存储    │
                                           │ Kafka/Redis │  │ S3/OSS      │
                                           └─────────────┘  └────────────┘
                                                          ┌──────────────┐
                                                          │ 可观测/治理   │
                                                          │ LangSmith/ APM│
                                                          └──────────────┘
  • 前端层（Next.js）：交互、流式渲染（SSE/WebSocket）、移动端适配
  • API Gateway/BFF：认证、限流、缓存、数据聚合
  • 服务层：RAG/Agent/LangGraph 工作流、鉴权、审计、策略引擎
  • 数据层：向量库（语义检索）、关系库（元数据与业务）、对象存储（文档/模型）、消息队列（异步任务）
  • 观测与治理：Tracing、Metrics、日志、审计、评测、灰度与回滚

🧱 领域划分与服务拆分

11.2 领域划分（DDD 思维）

  • Content 域：文档采集、清洗、切分、索引、版本管理
  • Retrieval 域：检索与重排、策略管理（TopK/MMR/Hybrid/Time/User）
  • Generation 域：Prompt 模板、结构化输出、Guardrails
  • Agent 域：工具编排、计划与执行、多 Agent 协作
  • Governance 域：鉴权/审计/配额/敏感词/合规
  • Observability 域：链路追踪、指标、告警、回放、评测

11.3 服务拆分建议

  • ingest-svc：入库管道（ETL）、增量更新、回压控制
  • search-svc：检索与排序、混合检索、向量库访问适配
  • gen-svc：生成与解析、结构化与校验、成本控制
  • agent-svc：工具注册/执行、计划分解、回退/重试
  • workflow-svc：LangGraph 编排、状态持久化、断点恢复
  • bff：对前端暴露聚合接口与契约

🔐 多租户、认证与权限（RBAC/ABAC）

11.4 多租户模型

  • 单库多租户（tenant_id 列隔离）：实现简单，需行级/查询级隔离
  • 多库多租户：强隔离，成本高，适合大型企业/合规要求高
  • 混合模型：核心敏感域多库，非敏感域单库

11.5 认证与权限

  • 认证：OIDC（Auth0/Azure AD）、JWT（短期）、长会话（刷新 Token）
  • 授权：RBAC（角色 → 权限）、ABAC（属性驱动：部门、地区、敏感级别）
  • 数据权限：按文档来源/标签/部门进行元数据过滤
// 文件：src/ch11/authz.ts
export type User = { id: string; roles: string[]; dept?: string; tenantId: string };
export type Policy = (u: User, resource: any, action: string) => boolean;

export const rbac: Policy = (u, r, a) => {
  if (u.roles.includes('admin')) return true;
  if (a === 'read' && r.tenantId === u.tenantId) return true;
  return false;
};

export const abac: Policy = (u, r, a) => {
  if (r.sensitivity === 'high' && !u.roles.includes('compliance')) return false;
  if (r.dept && u.dept && r.dept !== u.dept) return false;
  return r.tenantId === u.tenantId;
};

export function can(u: User, r: any, action: string) {
  return rbac(u, r, action) && abac(u, r, action);
}

🗄️ 数据治理：版本、血缘、质量与隐私

11.6 文档与索引版本

  • 文档版本号/内容指纹（hash），索引记录 doc_version 与 embedded_at
  • 增量构建：对比新旧指纹，只重算变更片段
  • 回滚：保留历史索引快照，支持热切换

11.7 数据血缘

  • 记录片段来源（source、chunkId、offset、publishedAt、author）
  • 回答必须携带引用，支持溯源与审计（谁在何时基于何数据给出结论）

11.8 隐私与合规

  • PII/敏感词检测：入库与出库双向校验
  • 数据脱敏：展示层屏蔽敏感字段，或以最小必要原则暴露
  • 保留策略：合规要求的保留周期与删除流程（软删除/硬删除）

⚙️ 稳定性：容错、重试、熔断、降级

11.9 重试与退避

// 文件：src/ch11/retry.ts
export async function withRetry<T>(fn: () => Promise<T>, tries = 3, base = 200) {
  let last: any;
  for (let i = 0; i < tries; i++) {
    try { return await fn(); } catch (e) { last = e; }
    await new Promise(r => setTimeout(r, base * Math.pow(2, i) + Math.random()*100));
  }
  throw last;
}

11.10 熔断与速率控制

// 文件：src/ch11/circuit.ts
export class CircuitBreaker {
  private failures = 0; private state: 'closed'|'open'|'half' = 'closed'; private openedAt = 0;
  constructor(private threshold = 5, private cooldownMs = 5000) {}
  async exec<T>(fn: () => Promise<T>) {
    if (this.state === 'open' && Date.now() - this.openedAt < this.cooldownMs) {
      throw new Error('circuit_open');
    }
    try {
      const out = await fn();
      this.failures = 0; this.state = 'closed';
      return out;
    } catch (e) {
      this.failures++;
      if (this.failures >= this.threshold) { this.state = 'open'; this.openedAt = Date.now(); }
      throw e;
    }
  }
}

11.11 降级策略

  • RAG：跳过 rerank、降低 TopK、改用 keyword + vector 混合
  • Agent：限制工具调用次数、优先内部数据、关闭高成本工具
  • 生成：缩短输出、降低温度、减少并行任务数量

🚀 性能：缓存、并发、批处理与成本控制

11.12 分层缓存

  • 输入 → 检索结果（短期）
  • RAG 输出（包含引用）
  • Prompt 模板与少样本示例
  • 工具调用（外部 API）
// 文件：src/ch11/cache.ts
export class TTLCache<T=any> { private m = new Map<string, {v:T,t:number}>();
  get(k:string, ttl=60000){ const e=this.m.get(k); if(!e) return; if(Date.now()-e.t>ttl){ this.m.delete(k); return; } return e.v; }
  set(k:string, v:T){ this.m.set(k,{v,t:Date.now()}); }
}

11.13 并发与批处理

  • 嵌入批处理：embeddings.embedDocuments 合并请求
  • 检索并发：多个集合/策略并发检索，统一重排
  • 工具批处理：对同类型调用进行合并

11.14 成本治理

  • 模型分层：大模型兜底，小模型为主（3-small embedding；gpt-4o-mini 推理）
  • 配额与预算：按租户/部门限额、告警与熔断
  • 成本审计：按请求记录 token 与费用，月度报表

🧠 工作流：LangGraph 在企业的落地

11.15 模式与建议

  • 有限状态机表达复杂流程：分支、循环、人工中断/恢复
  • 状态持久化：数据库记录状态、RunId、时间线、错误分类
  • 回放与审计：保存输入、检索命中、生成输出、引用与决策

11.16 典型流程

  • 入库（Ingest）图：上传 → 清洗 → 切分 → 嵌入 → 构建索引 → 完成通知
  • RAG 问答图：检索 → 融合 → 生成 → 守护 → 反馈
  • 协同图（RAG × Agent）：规划 → 执行 → 反思 → 回环

🌐 接口规范与 BFF 设计

11.17 API 契约示例

// 文件：src/app/api/rag/route.ts
import { NextRequest } from 'next/server';
export const runtime = 'edge';

export async function POST(req: NextRequest) {
  const { q, domain = 'news' } = await req.json();
  // 校验/鉴权/审计省略
  // 伪实现
  const result = { answer: '...', citations: [{ source: 'docs/policy/travel.md', chunkId: '1' }], confidence: 0.78 };
  return Response.json({ ok: true, data: result });
}

11.18 SSE/流式输出与移动端适配

  • SSE：适合顺序输出（回答/进度）；移动端用事件驱动渲染
  • WebSocket：适合双向互动（Agent 工具回调展示）
  • 移动端：骨架屏、渐进披露（分段回答）、弱网重连

🧰 部署基线：容器与多环境

11.19 环境与配置

  • 环境：Dev/Stage/Prod；隔离向量库与数据库
  • 配置：ENV + 加密参数（KMS/Secrets Manager）；按租户配置检索策略
# 文件：deploy/.env
NODE_ENV=production
OPENAI_API_KEY=sk-...
LANGSMITH_API_KEY=ls-...
VECTOR_COLLECTION=rag_news

11.20 Docker Compose（示意）

# 文件：deploy/docker-compose.yml
version: '3.9'
services:
  app:
    build: ..
    environment:
      - NODE_ENV=production
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    ports:
      - '3000:3000'
    depends_on:
      - chroma
  chroma:
    image: chromadb/chroma
    ports:
      - '8000:8000'
    volumes:
      - ./data/chroma:/data

11.21 灰度与回滚

  • 蓝绿发布/金丝雀：按租户或百分比切流
  • 新 Prompt 与模型策略走灰度；指标异常自动回滚到基线

📊 可观测与告警

11.22 三大支柱

  • Traces：端到端链路（含检索与生成）
  • Metrics：QPS、P95、错误率、成本、命中率
  • Logs：关键节点结构化日志与审计日志

11.23 告警与自愈

  • 异常指标阈值触发：错误率/延迟/成本飙升
  • 自愈动作：降级策略、熔断、重启有状态图（resume）

🚀 实战项目：企业知识中台架构落地

11.24 需求

  • 多租户接入：不同事业部共享平台但隔离数据
  • 多源数据：官网/内网/系统导出（CSV/PDF/HTML/Confluence）
  • 全链路追溯：每条回答可定位到来源与版本
  • 运营侧报表：满意度、命中率、成本、TOP 问题

11.25 关键模块设计

  • 数据入库流水线 + 版本与血缘
  • RAG 服务：策略化检索 + 引用约束模板
  • Agent 工具：工单/搜索/第三方 API
  • 工作流：LangGraph 编排 + 审批中断
  • 运营与观测：报表 + 告警 + 追溯

11.26 风险与对策

  • 幻觉：强制引用与拒答路径、缩短上下文、Guardrails
  • 数据新鲜度：定时增量与实时事件流（CDC）
  • 成本：分层模型与缓存；限额与预算
  • 合规：权限/审计/数据本地化（按地区）

📚 延伸链接

  • 云原生架构模式：https://12factor.net/
  • LangGraph：https://langchain-ai.github.io/langgraph/
  • 架构可观测：https://opentelemetry.io/
  • 企业安全与合规参考：https://owasp.org/

✅ 本章小结

  • 构建了企业级 AI 应用从前端到治理的全景架构
  • 给出多租户、权限、数据治理、稳定性、性能与成本的一揽子方案
  • 基于 LangGraph 的工作流与可观测形成工程闭环，支撑生产可用

🎯 下章预告

下一章《高性能 AI 应用优化技术》中，我们将：

  • 深入服务端与前端性能优化策略
  • 模型选择、缓存层次、并发调度与吞吐优化
  • 成本与性能的平衡与动态自适应

最后感谢阅读！欢迎关注我，微信公众号：《鲫小鱼不正经》。欢迎点赞、收藏、关注，一键三连！！！

avatar
文章
阅读
粉丝