真正决定企业私有化部署 AI Agent 成败的,往往不是模型本身,而是从模型到业务系统之间的那条工程链路。KylinWork 这类企业级 Agent 平台被反复讨论,原因也在于它把单个智能体功能拉宽成了一个可落地的系统:模型推理、智能体编排、知识库检索、工具调用、权限治理和运维监控,都要在私有网络内闭环。对很多团队来说,这意味着第一次要在自有资源池里建设一套带 GPU、带向量库、带审计日志的 AI 平台。这篇内容按企业私有化部署 AI Agent 的落地方案拆解,讲清楚每一层做什么、为什么这样做、怎么验证,以及出问题之后从哪里开始查。
1. 先明确私有化部署 AI Agent 要解决的真实问题
1.1 私有化不是把云端方案搬回家,而是重建整个治理链路
很多团队一开始会把私有化部署理解为“把云端对话机器人装进内网服务器”,真正动手后才发现,模型可以下载、镜像可以启动,但业务要的是可以持续迭代、可审计、可回滚的企业系统。
企业私有化部署 AI Agent 的核心目标通常有三类:
- 数据不出私有网络,避免业务数据、用户信息、文档内容经过外部服务。
- 模型和工具可自定义,能够接入企业内部的数据库、审批流、工单系统、监控系统。
- 权限和审计可控,谁在什么时间问了什么问题、调用了哪个工具、模型消耗了多少 token,都能追踪。
所以私有化部署并不是省掉云端依赖,而是把原来由云平台承担的编排、路由、权限、监控、存储全部转移到企业内部系统里。KylinWork 这类方案之所以有参考价值,是因为它背后是一套完整的工程结构,而不是单个模型 API 的简单转发。
1.2 从 KylinWork 拆解出的核心链路:模型、智能体、工具与治理
一份可落地的私有化 AI Agent 方案,至少需要包含以下五层:
- 模型服务层:承载大模型推理,可以是本地 GPU 推理服务,也可以是私有网络内的模型 API。
- 智能体编排层:负责理解用户意图、拆解任务、决定调用哪个工具、汇总结果。
- 知识库与检索层:负责把企业内部文档向量化、存储、检索,给模型提供事实依据。
- 工具执行层:连接业务系统,封装修单、查询、审批等动作,并校验参数和权限。
- 治理与运维层:包括用户认证、权限隔离、审计日志、监控告警、版本发布和回滚。
多数企业做私有化部署时,真正反复出问题的不是某一层单独运行不了,而是层与层之间的接口没设计好。比如模型返回了 JSON 但工具层没校验参数,知识库检索出来一堆无关片段但 prompt 里没有限制,用户权限能登录却控制不住工具调用。
1.3 SaaS 与私有化部署的关键差异
先看清差异,后面做技术选型才不会跑偏。
| 维度 | 云端 SaaS | 企业私有化部署 |
|---|---|---|
| 数据归属 | 数据经过服务商处理 | 数据存储和计算都在企业私有网络 |
| 模型选择 | 使用平台预置模型 | 可接入本地模型或私有化模型 API |
| 功能扩展 | 受平台能力限制 | 可对接内部系统,扩展业务工具 |
| 升级节奏 | 服务商统一升级 | 企业自己控制版本、灰度、回滚 |
| 运维职责 | 服务商负责可用性 | 企业内部负责 GPU、网络、存储、日志 |
| 初始成本 | 按量付费,前期低 | 需要购入 GPU 资源和建设运维能力 |
| 合规适配 | 依赖服务商能力 | 更容易匹配内部审计、等保和行业监管要求 |
看过这张表之后,基本可以判断一个企业适不适合私有化部署。这里要提醒的是:私有化不天然比 SaaS 安全,它只是把安全责任转移到企业自己身上。如果企业没有专门的运维和日志审计能力,私有化后的风险并不会消失,只是换了责任人。
2. 从硬件到基础软件:部署环境要先想清楚再动手
2.1 模型选型决定 GPU 资源,而不是反过来
部署私有化 AI Agent 之前,最容易犯的错误是先把 Agent 框架跑起来,再去想模型跑在哪。实际应该反过来:先根据业务场景确定模型规模和并发要求,再推导出 GPU、内存、磁盘规格。
大模型推理的显存占用,和模型参数规模、序列长度、并发数强相关。以常见开源模型为例:
- 7B 级别模型,FP16 权重约 14GB,量化后约 6 到 10GB。
- 14B 级别模型,FP16 权重约 28GB,量化后约 12 到 18GB。
- 70B 级别模型,FP16 权重约 140GB,单卡通常无法直接加载,需要考虑多卡张量并行或更强量化方案。
但这只是权重占用,推理时 KV Cache、激活值、请求队列都会额外占用显存。生产环境不能只按模型权重大小买卡,要给并发请求留出余量。
2.2 用一个资源规划表说明常见部署规模
下面这张表给出的是常见私有化部署规模的参考,不是绝对标准。实际采购前要用真实负载和压测数据再确认。
| 部署场景 | 模型规模 | 参考 GPU 配置 | 内存 | 磁盘 | 说明 |
|---|---|---|---|---|---|
| 功能验证 | 7B 量化模型 | 1 张 24GB 显卡 | 64GB | 200GB SSD | 用于开发调试和小规模试用 |
| 部门级使用 | 14B 模型 | 1 到 2 张 48GB 显卡 | 128GB | 1TB SSD | 支撑几十到上百用户日常使用 |
| 企业级多节点 | 70B 或高并发小模型 | 多节点 GPU 集群 | 256GB 起 | 3TB 起 | 需要 K8s 调度、GPU 资源池、监控告警 |
磁盘规划不要忽略模型文件、向量数据库、日志和备份。一个 14B 模型文件通常占 28GB 左右,向量库会根据知识库文档规模增长,日志在 Agent 场景下增长很快,因为每一轮对话都可能记录用户输入、工具调用、模型返回和耗时。
2.3 前置组件清单与版本检查
私有化部署 AI Agent 的基础环境通常包括以下组件:
- Linux 服务器,推荐 Ubuntu 22.04 或兼容发行版。
- NVIDIA 驱动和 CUDA 运行环境。
- Docker Engine 和 Docker Compose 插件。
- 容器编排工具,生产环境常用 Kubernetes 和 Helm。
- NVIDIA Container Toolkit,用于让容器访问 GPU。
- 对象存储或共享文件系统,用于存放模型文件、知识库文档和备份。
启动部署前,先在服务器上执行几个基础检查命令:
nvidia-smi该命令能确认 GPU 驱动是否正常、显存是否可见。接着检查 GPU 型号和驱动版本,因为不同推理框架对 CUDA 版本有要求。
docker version docker compose version如果使用 Kubernetes,再检查 kubelet 和 kubectl 版本是否匹配。
kubectl version --client kubectl get nodes基础组件最容易出问题的地方是版本不匹配,而不是“没安装”。Docker 版本过低会导致 Compose 语法不兼容,NVIDIA 驱动与容器工具包版本不一致会导致容器内看不到 GPU,因此版本检查要写进部署检查清单。
2.4 学习环境、测试环境、生产环境的配置差异
| 环节 | 学习环境 | 测试环境 | 生产环境 |
|---|---|---|---|
| 模型 | 小模型或量化模型,能跑通即可 | 与生产同系列模型,降低版本差异 | 经过压测和评审的正式模型版本 |
| 数据 | 使用公开示例数据 | 脱敏后的业务数据 | 真实业务数据,需按等级保护 |
| 权限 | 不做严格要求 | 模拟真实角色权限 | 最小权限、审批流、双人复核 |
| 日志 | 控制台输出即可 | 接入统一日志平台 | 长期存储,具备审计检索能力 |
| 监控 | 可不做 | 基础 CPU、内存、GPU 监控 | 全链路监控,包含模型时延、token 消耗、工具异常率 |
| 升级 | 随意重装 | 保留快照后升级 | 灰度发布、回滚方案、变更窗口 |
不要用学习环境的标准要求生产环境,也不要在生产环境保留学习阶段的明文密码、默认账号和全开放网络策略。
3. 用 Docker Compose 快速拉起一套私有化 Agent 最小环境
3.1 最小环境由哪几个模块组成
先不要一步到位建设 Kubernetes 集群。要快速验证私有化 AI Agent 方案,可以使用 Docker Compose 拉起最小环境。最小环境至少包含:
- 网关:统一接收应用请求,完成鉴权和路由转发。
- 智能体引擎:执行业务逻辑,是大模型推理服务和业务工具之间的协调者。
- 模型推理服务:加载开源大模型,提供兼容 OpenAI 格式的接口。
- 向量数据库:存储知识库文档向量,支撑检索增强生成。
- 管理控制台:配置模型、工具、用户、审计策略。
下面这份 Compose 文件是示例,镜像名称和版本要根据企业内部构建结果替换,不能直接照搬到生产环境。
services: postgres: image: postgres:15.6 environment: POSTGRES_USER: kylin POSTGRES_PASSWORD: change-me POSTGRES_DB: kylinwork volumes: - pg-data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U kylin"] interval: 10s timeout: 5s retries: 5 milvus: image: milvusdb/milvus:v2.4.5 command: ["milvus", "run", "standalone"] environment: ETCD_ENDPOINTS: etcd:2379 depends_on: - etcd etcd: image: quay.io/coreos/etcd:v3.5.14 environment: ETCD_AUTO_COMPACTION_MODE: revision ETCD_AUTO_COMPACTION_RETENTION: "1000" model-inference: image: vllm/vllm-openai:v0.6.4.post1 command: [ "--model", "/models/Qwen2.5-14B-Instruct", "--served-model-name", "local-model", "--max-model-len", "8192", "--gpu-memory-utilization", "0.9" ] volumes: - /data/models:/models ports: - "8001:8000" deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] agent-engine: image: kylinwork/agent-engine:0.1.0 environment: MODEL_BASE_URL: http://model-inference:8000/v1 MODEL_NAME: local-model VECTOR_DB_HOST: milvus DATABASE_URL: jdbc:postgresql://postgres:5432/kylinwork depends_on: - postgres - milvus - model-inference gateway: image: kylinwork/gateway:0.1.0 environment: AGENT_ENGINE_URL: http://agent-engine:8080 ports: - "8080:8080" depends_on: - agent-engine console: image: kylinwork/console:0.1.0 environment: GATEWAY_URL: http://gateway:8080 ports: - "80:80" depends_on: - gateway volumes: pg-data:这份配置解决了三件事:第一,模型推理服务和智能体引擎都在同一个 Docker 网络中互联;第二,知识库和元数据库有独立存储;第三,网关对外暴露,业务系统只通过网关访问智能体能力。
3.2 模型服务接入的两种方式
私有化部署环境下,模型服务通常有两种接入方式。
第一种是接入私有网络内已有的模型 API,只需配置接口地址和密钥。优点是模型部署由专门的算法团队负责,Agent 平台不直接管理 GPU;缺点是依赖外部服务稳定性,接口协议需要兼容 OpenAI 格式。
第二种是在 Agent 平台所在的主机上直接运行本地推理服务。使用 vLLM、Ollama 等推理框架加载开源模型。这种方式链路短,便于排错,适合绝大多数企业内部私有化场景。
vllm serve /models/Qwen2.5-14B-Instruct \ --served-model-name local-model \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --port 8000启动后,模型服务会暴露一个兼容 OpenAI 格式的接口。智能体引擎只需要配置MODEL_BASE_URL和MODEL_NAME,就能完成模型对接。
需要注意的是,--max-model-len决定了模型单次可以处理的上下文长度,这个值越大,显存占用越高。它会影响长文档问答、工具调用结果的拼接能力,但也会有更高显存消耗,需要结合真实场景调整。
3.3 用 Spring Boot 写一个最小客户端
服务端跑起来之后,业务系统如何对接 Agent?这里给一个 Spring Boot 客户端的示例思路。客户端只需要向网关发送请求,不直接感知模型服务和向量库。
先添加基础依赖:
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>然后使用 Spring Boot 的 RestClient 调用网关接口:
import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; import org.springframework.web.client.RestClient; @RestController public class AgentClientController { private final RestClient restClient; public AgentClientController() { this.restClient = RestClient.builder() .baseUrl("http://agent-gateway:8080") .defaultHeader("Authorization", "Bearer " + System.getenv("AGENT_TOKEN")) .build(); } @PostMapping("/ask") public AgentReply ask(@RequestBody String message) { ChatRequest request = new ChatRequest("session-001", message); AgentReply reply = restClient.post() .uri("/v1/chat") .body(request) .retrieve() .body(AgentReply.class); return reply; } }这个客户端的关键点有三个:网关地址要通过配置管理,不写死到代码里;每次请求都携带认证 token;业务侧要使用请求 ID 关联日志,方便后续追踪整条链路。
3.4 部署后如何确认服务健康
服务起来后,不能只看容器运行状态,还要依次确认三个链路:
第一,模型推理服务是否正常加载模型。执行:
curl http://localhost:8001/v1/models如果返回模型列表,说明模型服务已就绪。
第二,网关是否能转发请求到智能体引擎。调用健康检查接口:
curl -H "Authorization: Bearer token" http://localhost:8080/health第三,端到端能否完成一次问答。直接向网关发送消息:
curl -X POST http://localhost:8080/v1/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer token" \ -d '{"session_id":"test-1","message":"你好,请介绍一下私有化部署注意事项"}'如果前两步都正常,但第三步失败,问题通常出在智能体引擎到模型服务、向量库或数据库的连接上,此时要去容器日志里找具体报错。
4. Agent 编排、工具调用与知识库检索的实现细节
4.1 Agent 的工作循环:从用户输入到工具结果汇总
AI Agent 和普通问答接口最大的区别,是它具备“感知、规划、行动、总结”的工作循环。一条用户消息到达智能体引擎后,大致会经历以下过程:
- 识别用户意图,判断是普通问答、知识库检索,还是需要调用业务工具。
- 如果需要调用工具,解析工具名称和参数。
- 调用工具前做参数校验和权限校验。
- 把工具返回结果交给模型,让模型组织最终回答。
- 记录整轮调用的日志,包括模型输入、模型输出、工具结果、耗时。
这个循环决定了一个重要设计原则:模型并不是唯一可信来源,工具返回结果才是事实依据。公司内部“请假余额多少”“工单当前状态”这类问题,不能靠模型记忆,必须让 Agent 调用真实业务系统查询。
4.2 工具注册:模型要能“看到”工具的入参
要让模型正确选择工具,需要把工具的定义用结构化 JSON Schema 描述出来,并在每次请求时连同用户消息一起发送给模型。示例:
{ "name": "query_leave_balance", "description": "查询指定员工的剩余年假天数", "parameters": { "type": "object", "properties": { "employee_id": { "type": "string", "description": "员工编号" } }, "required": ["employee_id"] } }这里的description直接影响模型对工具的理解。描述写得越清楚,模型选错工具的几率越低。字段名要使用业务系统里的统一命名,不要同一个概念在不同工具里叫不同名字。
工具调用返回的数据格式也需要规范。常见错误是工具层返回一个很长的业务对象,里面包含大量无关字段,模型看到后不知道哪些是关键结果,最终回答偏离主题。建议工具层统一返回精简后的结果结构:
{ "status": "success", "data": { "employee_id": "E1001", "annual_leave": 12, "unit": "day" } }4.3 RAG 参数:检索不准时先改这几个配置
知识库检索是私有化 AI Agent 的高频配置项。很多团队部署完知识库后,第一个问题是“文档明明传了,为什么模型回答不准确”。最优先检查的是检索参数。
| 参数 | 常见默认值 | 调大影响 | 调小影响 | 适用场景 |
|---|---|---|---|---|
| chunk_size | 500 字符 | 信息更完整,但检索粒度粗 | 片段更独立,但可能切断语义 | 按文档段落合理调整 |
| chunk_overlap | 50 字符 | 保留上下文衔接 | 减少向量库重复内容 | 段落之间有关联时使用 |
| top_k | 5 | 上下文更丰富,但可能引入噪声 | 回答更聚焦,但信息不足 | 按知识库准确度调整 |
| score_threshold | 0.65 | 检索更严格,召回少 | 召回多,但容易混入无关片段 | 精确问答建议调高 |
| embedding_model | 视技术选型 | 影响向量维度 | 影响语义理解能力 | 建议与模型语言能力匹配 |
举一个实际案例:知识库是一份 50 页的规章制度文档,如果chunk_size设得过大,一个片段可能包含多个制度条目,检索回来之后语义混杂;如果top_k设置过大,模型一次接收太多片段,回答时会拿无关片段“凑数”。调优时,先固定chunk_size,再调top_k和score_threshold,一次只改一个参数。
4.4 典型问题:模型不调用工具,或不按 JSON 返回
模型不调用工具,这是 Agent 落地中最常见的问题。原因大体有三类:
- 工具描述不清晰,模型不知道这个工具是干什么的。
- 用户问题本身不需要工具,模型判断可以直接回答。
- 模型能力较弱,无法稳定理解工具调用的 JSON 格式。
第一类问题通过优化工具description解决,第二类属于真实判断,不处理。第三类需要升级模型,或使用更稳定的结构化输出能力,不能只靠改提示词。
如果模型调用了工具,但返回的结构不符合预期,工具执行层必须做容错。工具调度器应该捕获解析异常并返回给模型,让模型重新组织回答,而不是直接抛出错误中断整轮对话。
5. 安全、权限与审计:私有化部署最不能省略的环节
5.1 数据边界:模型推理、知识库和日志都要在私有网络内闭环
私有化部署和云端 SaaS 最大的区别,是数据边界一定要清晰。企业内部文档、业务数据、用户身份信息一旦进入模型上下文,理论上就会出现在模型服务的日志和缓存中。这会带来三个要求:
- 模型服务必须在企业私有网络内运行,不经过任何外部链路。
- 向量数据库中的数据要有访问控制,不能允许任意服务直接读取。
- 日志中如果包含敏感字段,需要脱敏后再落盘。
如果企业有等保或行业监管要求,还需要进一步设计数据分级和访问审计。这里的目标不是“绝对安全”,而是让每一次数据访问都有边界、有身份、有记录。
5.2 用户权限与工具授权要分开设计
Agent 平台通常有两套权限体系。一套是面向“用户”的,决定用户能否登录、能否使用某个 Agent、能否查看审计日志;另一套是面向“工具”的,决定当前用户能否让 Agent 触发某个业务动作。
这两套权限必须分开。一个用户可能能查看工单,但未必能修改工单;可能能查询请假余额,但未必能提交请假审批。如果把工具权限等同于用户权限,Agent 很容易变成越权操作的通道。
工具层在接收到 Agent 的调用请求时,不能只校验工具参数合法性,还要校验当前用户是否被授权执行该工具。这条校验应该在工具执行层完成,而不是完全依赖模型自行判断。
5.3 Prompt 注入与工具异常要纳入防护范围
私有化 AI Agent 上线后,会遇到两类容易被忽视的安全问题。
第一类是提示词注入。用户在上传文档或提问时,可能在内容中嵌入“忽略之前的规则”等指令,试图诱导模型输出不该输出的话。对策包括:限制上传文档类型、对系统提示词做隔离、要求模型在不确定时拒绝回答、在推理前增加内容审核。
第二类是工具调用异常。工具层是 AI 对外部系统的入口,如果输入参数没有校验,Agent 可能把不合法参数传给下游系统。比如查询接口被传入超长字符串、删除操作被误触发等。工具层必须做参数白名单校验,对危险操作增加人工确认流程。
5.4 审计日志和监控指标定义
私有化部署上线后,审计日志不是可选项。每一轮 Agent 请求都应该记录以下字段:
{ "request_id": "req_20250101_001", "user_id": "zhangsan", "agent_id": "hr-assistant", "model": "local-model", "prompt_tokens": 1280, "completion_tokens": 320, "tool_calls": [ { "tool": "query_leave_balance", "args": {"employee_id": "E1001"}, "status": "success" } ], "latency_ms": 3840, "error_code": null, "created_at": "2025-01-01T10:00:00Z" }监控指标方面,除了常规的 CPU、内存、磁盘、网络,Agent 场景还必须关注:
- 模型推理时延,尤其是首 token 延迟和总响应时间。
- token 消耗量,按用户、按 Agent、按功能维度统计。
- 工具调用失败率和平均工具耗时。
- 知识库检索召回率和检索耗时。
- 并发请求排队数,队列积压会直接导致用户体验恶化。
6. 运行验证、压力测试与上线前检查
6.1 功能验证:不要只验证“能回答”
很多私有化部署在验收时,只验证了普通问答能返回结果,就认为系统正常。实际上,Agent 平台至少要覆盖以下功能验证:
| 验证项 | 验证方法 | 预期结果 |
|---|---|---|
| 普通问答 | 发送知识性问题 | 返回准确且引用来源 |
| 知识库问答 | 发送只存在于内部文档中的问题 | 答案基于文档,检索无报错 |
| 工具调用 | 发送需要查询业务系统的问题 | 工具被调用,返回真实数据 |
| 权限拦截 | 使用低权限账号调用敏感工具 | 工具被拒绝,日志有记录 |
| 流式输出 | 客户端发起流式请求 | 事件按顺序返回 |
| 异常恢复 | 手动停止模型服务后发起请求 | 错误信息明确,恢复后请求可继续 |
功能验证时建议准备一套真实业务场景的测试用例集。用例集要包含正常路径、边界路径和异常路径。比如“查询请假余额”这一功能,至少要覆盖:有余额、余额为零、员工不存在、员工编号为空、权限不足。
6.2 并发验证:先压模型服务,再压整体链路
私有化 AI Agent 的性能验证和传统接口压测不同。传统接口压测看 TPS,Agent 场景还有一个关键指标是并发会话数和 token 吞吐量。
建议压测分三步进行:
- 单独压测模型推理服务,确认单卡在一个批次下能稳定支撑多少并发请求。
- 单独压测知识库检索服务,确认向量检索在多少个并发查询下不超时。
- 通过网关发起端到端压测,观察模型排队、工具调用、输出拼接的综合表现。
压测时要重点观察两个指标:GPU 显存使用率和请求排队数。显存接近上限会导致 OOM,排队数增长过快说明模型并发上限配置不合理。
6.3 上线前检查清单
上线前一天,建议至少完成以下检查:
| 检查项 | 操作 | 通过标准 |
|---|---|---|
| GPU 可见性 | 在 Agent 容器内执行nvidia-smi | 返回实际 GPU 信息 |
| 模型文件完整性 | 比对模型文件哈希或大小 | 与发布前记录一致 |
| 配置文件外置 | 检查密码、密钥是否放入环境变量或密钥管理 | 代码仓库无明文敏感信息 |
| 数据库备份 | 执行一次备份并验证恢复 | 备份文件可恢复 |
| 日志目录挂载 | 检查容器日志是否写入宿主机持久化目录 | 重启容器日志不丢失 |
| 告警规则 | 配置 GPU 显存、OOM、接口错误率告警 | 告警策略已生效 |
| 回滚方案 | 确认上一版镜像和部署脚本可用 | 能在 30 分钟内回滚 |
6.4 备份、回滚与升级策略
AI Agent 平台的备份对象不只是数据库,还包括:向量数据库索引、模型配置文件、工具定义、提示词模板、审计日志。
建议备份策略如下:
- 数据库每天全量备份,保留最近 7 天。
- 向量数据库定期导出全量索引,保留至少 3 份归档。
- 模型文件和依赖包单独归档,避免升级时因网络原因无法重新下载。
- 每次变更配置文件之前,先备份当前版本,并记录变更人、变更时间、变更原因。
版本升级时,不要直接在生产环境替换镜像。比较稳妥的顺序是:先在测试环境用同一份模型和同一批用例回归,再在生产环境灰度一个节点,最后全量发布。模型版本升级影响最大,通常需要重新压测并核对一批 golden questions 的输出。
7. 高频问题与排查路径
7.1 现象、根因、检查命令、处理的对照表
这节把私有化部署中最常见的几类问题整理成一张表,便于对照处理。
| 问题现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| 容器内看不到 GPU | 未安装 NVIDIA Container Toolkit | 在容器内执行nvidia-smi | 安装 toolkit 并重建容器 |
| 模型加载很慢或一直重启 | 模型文件在慢磁盘,或显存不足 | 查看模型服务日志、dmesg | 模型文件放入 SSD,降低并发或换小模型 |
| 请求超时 | 模型并发配置过低,或知识库检索慢 | 查看网关日志、模型排队日志 | 调整模型并发参数,优化向量检索索引 |
| Agent 不调用工具 | 工具描述不清晰、模型能力不足、权限缺失 | 查看本轮请求发给模型的工具列表和响应 | 优化工具 description,检查工具授权 |
| 知识库回答完全错误 | chunk_size 过大或 top_k 过大 | 在控制台开启检索可视化,查看召回片段 | 调整 RAG 参数,逐个验证 |
| 工具调用报参数解析失败 | 模型返回了非标准 JSON | 查看工具调度器日志 | 增加 JSON 解析容错,启用结构化输出 |
| 权限控制失效 | 只做了用户权限,没做工具权限 | 使用低权限账号发起工具调用 | 补工具层授权校验 |
7.2 排查顺序:从入口层到模型层
Agent 出问题时,不要一上来就怀疑模型。建议按以下顺序排查:
- 请求是否到达网关。查看网关访问日志,确认没有鉴权失败和路由错误。
- 智能体引擎是否收到请求。确认消息是否被正确解析,上下文是否带上。
- 模型是否正常返回。查看模型服务日志,确认没有超时、上下文超限、GPU 异常。
- 工具层是否成功执行。查看工具调用日志,确认参数校验和权限校验结果。
- 检索结果是否合理。查看向量库召回片段,确认与用户问题相关。
- 最终回答是否拼接了正确信息。确认没有丢信息、加戏或胡编。
这条链路中,日志是最重要的线索。如果每一层都有完整的request_id,排查速度会快很多;如果日志缺失,排错会退化成“猜”。
7.3 三个容易反复出现的具体坑
第一个坑:容器内 GPU 不可用。很多团队在宿主机上执行nvidia-smi正常,但容器内看不到 GPU。原因多半是 Docker 启动参数没有带上 GPU 设备,或者 NVIDIA Container Toolkit 没安装。使用 Docker Compose 时,要确认deploy.resources.reservations.devices配置是否存在。
第二个坑:模型并发一上来就 OOM。显存规划只看权重,忽略 KV Cache。高并发场景下,KV Cache 可能占数百 MB 到几 GB。应对方法是降低--max-model-len、降低--gpu-memory-utilization、限制并发数,并在压测中逐步调参。
第三个坑:Agent 回答看似合理,但实际上没有调用工具。这种问题最隐蔽,因为它不报错。排查方式是查看日志中是否有tool_calls记录。如果没有,说明模型认为可以直接回答,或工具定义没生效。此时先检查工具是否成功注入请求,再看模型是否支持 function calling 格式。
8. 最佳实践:把这套方案变成可维护的生产系统
8.1 可直接复用的检查清单
以下清单是落地时可以直接复制到内部文档里的版本。
环境检查清单:
- GPU 驱动与推理框架版本匹配。
- Docker 和 Compose 插件版本满足要求。
- 模型文件所在磁盘空间充足,且有备份。
- 容器可以正常访问 GPU。
- 私有网络内所有依赖服务端口互通。
上线前检查清单:
- 密钥、密码全部配置外置。
- 数据库和向量库已完成备份并演练恢复。
- 审计日志字段完整,且不包含明文敏感信息。
- 告警规则已覆盖 GPU 显存、接口错误率、队列积压、磁盘空间。
- 回滚方案已经过测试。
排错清单:
- 先看日志,不要盲目重启服务。
- 按网关到模型层的顺序逐步定位。
- 每次只改一个配置参数,改完立即验证。
- 所有配置文件变更都要有记录。
8.2 多环境与版本治理建议
私有化 AI Agent 和普通业务系统一样,需要版本治理。模型文件、Agent 编排配置、工具定义、提示词模板,都应该纳入版本管理。
建议把提示词模板、工具定义和 Agent 流程配置用 YAML 或 JSON 文件管理,而不是只存在数据库里。这样变更时可以走代码评审流程,回滚时只需恢复配置文件。
模型服务的升级要更谨慎。推荐先准备一个 golden questions 数据集,里面包含普通的问答、知识库检索、工具调用、权限拒绝、异常输入等若干条用例。每次升级模型后,都先跑一遍 golden questions,对比输出差异,再决定是否全量发布。
8.3 学习路径:从跑通到深入理解 Agent
对想深入掌握这套方案的开发者,学习路径可以这样安排:
- 先跑通最小部署,理解网关、智能体引擎、模型服务、向量库之间的调用关系。
- 学习大模型推理框架,掌握模型加载、并发控制、显存管理的基本概念。
- 理解 function calling 和工具注册,写两到三个真实业务工具连上来。
- 学习 RAG,掌握文档切分、向量化、检索召回和 prompt 拼接。
- 再看 Spring Boot 或 Java 客户端如何对接,完成一个真实业务场景的端到端闭环。
- 最后补上安全、权限、审计、压测和监控,把系统从“能跑”推进到“能维护”。
8.4 下一步扩展方向
当前方案依然有大量扩展空间。比较实际的方向包括:
- 多模型路由:根据任务难度路由到不同规模的模型,降低整体推理成本。
- 多智能体协作:把复杂任务拆给多个专用 Agent,由编排层统一调度。
- 更细粒度的成本核算:按部门、按用户、按功能统计 token 消耗,推进内部成本透明。
- 模型评测平台:建设自动化的模型回归评测能力,让模型升级有数据支撑。
- 个人知识库联动:把企业内部文档、个人笔记、知识库统一接入检索层,提升智能体回答的覆盖面。
这套链路真正稳定之后,企业私有化部署 AI Agent 就不再是一个探索性项目,而会逐步变成一个可以被审计、被优化、被扩展的内部基础设施。