从 API 调用到智能体编排：基于 AgentScope Java + 通义千问构建生产级企业知识问答系统面向 Java 企业开发者的一篇完整实战文章：不只演示“能跑”，而是系统说明如何把LLM 调用、RAG 检索、多智能体协作、会话记忆、可观测性、弹性治理与高并发扩展组合成可落地的企业级 AI 问答平台。一、为什么企业知识问答系统不能只停留在“调个大模型接口”很多团队在建设企业 AI 问答系统时，第一步往往是把用户问题直接转发给模型，然后把返回结果展示到页面。这种方式适合做 Demo，但很快会在真实业务中暴露问题：知识不可信大模型具备强泛化能力，但企业制度、流程、组织架构、产品细节都属于私域知识。如果没有检索增强，模型会出现“听起来合理但其实错误”的回答。系统不可控只做简单提示词拼接，很难对回答链路、工具调用、越权访问、响应耗时、失败重试进行治理，更难满足企业的审计和稳定性要求。并发场景容易失稳在高峰期，向量检索、大模型调用、外部业务系统查询往往同时发生。没有线程池隔离、限流、缓存和降级策略，系统吞吐会迅速恶化。缺乏工程可维护性如果所有逻辑都写在 Controller 或单个 Service 里，后续想扩展多知识域、多模型、多租户、多渠道接入时，重构成本会很高。因此，真正的企业级 AI 问答系统，目标不应只是“回答问题”，而应是：回答基于可信知识推理链路可观测、可治理高并发下稳定可扩展面向多场景可复用、可演进二、本文要解决的核心问题本文将以一个“企业知识问答系统”为案例，系统升级传统教程式文章的深度，重点回答以下四类问题：原理层AgentScope Java 在架构上到底解决了什么问题？ReAct、Router、RAG、Memory 在链路中如何配合？架构层如何把问答系统拆成接入层、编排层、检索层、工具层和基础设施层，避免把 AI 功能做成一个不可维护的“黑盒服务”？工程层如何处理高并发、大模型限流、向量检索热点、外部系统慢调用、SSE 流式输出、缓存、熔断和降级？代码层如何给出接近生产可用的 Java 示例，而不是只有几段演示代码？三、目标系统定义：一个真正可落地的企业 AI 问答平台3.1 业务目标系统需要支持以下典型问题：“公司的年假规则是什么？”“新员工报销流程怎么走？”“帮我查一下工号 E1024 的年假余额”“我的电脑无法连接 VPN，帮我提交一张 IT 工单”“总结一下本季度销售激励政策变更”这意味着系统不仅要会“回答”，还要具备：企业文档检索能力外部业务系统查询能力工具调用与结果归一化能力多轮对话上下文记忆能力高并发服务能力3.2 非功能目标一个生产级系统至少要满足以下非功能要求：维度目标可用性支持限流、重试、熔断、降级性能常规问答秒级响应，热点问题毫秒级缓存命中并发支持多用户并行会话，检索与工具调用异步化安全用户身份透传、工具权限校验、敏感信息脱敏可观测链路追踪、指标监控、结构化日志可扩展可切换模型、可新增知识域、可扩展更多工具四、总体架构设计：从单 Agent 到分层智能体平台4.1 分层架构┌──────────────────────────────────────────────────────────────┐ │ 用户接入层 │ │ Web / App / 钉钉 / 企业微信 / OpenAPI / 管理后台 │ └──────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ API 网关层 │ │ 鉴权、租户隔离、限流、审计、灰度、统一入口 │ └──────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ AI 编排与应用服务层 │ │ Session 管理 / Prompt 组装 / Router / Workflow / Memory │ └──────────────────────────────────────────────────────────────┘ │ │ │ ▼ ▼ ▼ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ │ FAQ / Policy Agent │ │ RAG Agent │ │ Action Agent │ │ 快速问答 │ │ 检索增强回答 │ │ 工具调用与业务执行 │ └──────────────────────┘ └──────────────────────┘ └──────────────────────┘ │ │ │ └────────────┬───────┴────────────┬───────┘ ▼ ▼ ┌──────────────────────────────────────────────────────────────┐ │ 能力支撑层 │ │ DashScope / Embedding / Vector DB / Redis / MQ / Biz API │ └──────────────────────────────────────────────────────────────┘4.2 核心职责拆分为了避免系统职责耦合，建议明确以下边界：Controller 层只负责协议转换、参数校验、用户身份透传、流式输出。Application 层负责编排一次完整问答请求，包含会话读取、意图路由、知识检索、工具执行、结果聚合。Domain 层承载问题分类、知识答案组装、引用策略、权限校验等业务规则。Infrastructure 层对接模型服务、Redis、向量库、ES、第三方业务系统。这种分层有两个关键价值：可以把“AI 能力”从“业务通道”中解耦。可以把“模型调用”从“应用规则”中解耦。五、核心技术原理：AgentScope Java 在系统里究竟扮演什么角色5.1 AgentScope Java 的价值不只是 SDK 封装很多人会误以为智能体框架只是对 LLM HTTP API 的一次“漂亮包装”。实际上，AgentScope Java 的价值在于提供了更高层的抽象：Agent 抽象让系统从“调用模型”升级为“让角色完成任务”。Tool 抽象把企业系统 API 映射为可供模型调用的结构化能力。Memory 抽象让多轮对话从拼字符串升级为可管理的上下文机制。Workflow / Multi-Agent 抽象让复杂任务从单提示词变成可治理的编排链路。也就是说，AgentScope Java 帮助 Java 团队把 AI 应用从“接口级集成”提升到“架构级集成”。5.2 ReAct 模式的本质ReAct 的核心不是“让模型多想几步”，而是将一次请求拆分为：Reason分析用户问题，判断是否需要查资料、调用工具、继续追问。Act调用知识检索、业务查询、工单提交等外部能力。Observe观察工具返回结果，决定下一步是否继续行动。Respond基于外部证据和推理结果生成最终回答。这比直接让模型“一次性作答”更适合企业场景，因为企业问答需要的是基于证据的回答链路。5.3 RAG 不是“查向量库”这么简单一个成熟的 RAG 链路通常包括：文档解析与切片元数据抽取向量化与入库查询重写召回重排序上下文压缩引用增强生成如果只做“query - embedding - topK”，容易出现：召回噪声大相似但不相关长文档上下文浪费多知识域混召引用不稳定所以，生产级 RAG 的重点不是“能检索”，而是“检索结果能为回答提供可信证据”。5.4 多智能体的价值不是所有场景都需要多智能体，但企业问答很适合使用：Router Agent负责意图分类与能力路由。RAG Agent负责知识检索增强回答。Action Agent负责调用 HR、OA、ITSM、CRM 等系统工具。Summary Agent负责长结果摘要、结构化输出与格式统一。这样做的优势在于：能力职责更清晰Prompt 更聚焦可按场景独立优化更容易做指标归因和链路排障六、生产级系统设计：从请求进来到答案返回的完整链路6.1 请求生命周期一条问答请求建议按以下链路执行：用户请求 - 鉴权与租户识别 - Session 加载 - 问题预处理与敏感信息脱敏 - 意图识别 - 路由到 FAQ / RAG / Action 流程 - 并发执行检索、工具调用或缓存查询 - 对结果进行重排、裁剪、组装 - 调用模型生成回答 - 答案后处理（引用、脱敏、格式化） - 写入 Memory / Trace / Metrics - 返回客户端6.2 路由策略建议并不是所有问题都应该走最重的链路。一个常见的工程化策略是“快慢车道”：问题类型处理策略问候、闲聊、通用问题直接走 FAQ Agent政策、制度、流程、知识解释走 RAG Agent个人数据查询、工单创建、审批动作走 Action Agent复杂综合问题Router 决定是否串行调用多个 Agent这样可以减少大模型与向量库的无效调用，显著提升吞吐和成本表现。七、项目结构设计：面向扩展而不是面向示例推荐采用如下项目结构：src/main/java/com/example/aiqa ├── AiQaApplication.java ├── config │ ├── AgentConfig.java │ ├── AsyncExecutorConfig.java │ ├── CacheConfig.java │ ├── ObservationConfig.java │ └── WebClientConfig.java ├── controller │ └── ChatController.java ├── app │ └── ChatApplicationService.java ├── domain │ ├── model │ │ ├── ChatCommand.java │ │ ├── ChatResult.java │ │ ├── IntentType.java │ │ ├── RetrievalChunk.java │ │ └── UserContext.java │ ├── service │ │ ├── IntentRouter.java │ │ ├── AnswerComposer.java │ │ └── PermissionService.java │ └── tool │ └── EnterpriseTools.java ├── agent │ ├── FaqAgent.java │ ├── RagAgent.java │ ├── ActionAgent.java │ └── SupervisorAgent.java ├── infrastructure │ ├── llm │ │ └── DashScopeGateway.java │ ├── memory │ │ └── RedisConversationMemoryStore.java │ ├── retrieval │ │ ├── RagSearchService.java │ │ ├── DocumentIndexer.java │ │ └── RerankService.java │ ├── remote │ │ ├── HrClient.java │ │ ├── ItsmClient.java │ │ └── KnowledgeApiClient.java │ └── support │ ├── TraceUtils.java │ └── MaskingUtils.java └── dto ├── ChatRequest.java └── ChatResponse.java这个结构的关键不在于目录漂亮，而在于它能支撑：多模型切换多知识库扩展多业务系统工具接入独立测试与压测清晰的职责边界八、从零实现：生产级依赖与配置8.1 Maven 依赖下面的依赖配置偏向企业项目实践，除 AgentScope 外，还补齐了缓存、校验、监控、弹性和 SSE 等能力。project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.5/version /parent groupIdcom.example/groupId artifactIdai-qa-system/artifactId version1.0.0/version properties java.version17/java.version agentscope.version0.1.0/agentscope.version resilience4j.version2