KylinWork：企业级AI Agent私有化部署方案实战解析

这次我们来看企业级 AI Agent 私有化部署方案KylinWork。企业做 AI Agent真正的分水岭不在提示词写得多花哨而在三件事模型能不能跑在自己可控的环境里、Agent 能不能接进现有业务系统、每一次调用链路能不能被审计和追溯。KylinWork 这类方案要解决的问题恰好就是这三件事。相比个人开发常用的云端 API 调用私有化部署的核心差异在于“数据不出域、权限可配置、调用有日志、模型可迭代”这也是很多金融、政务、制造类企业愿意投入资源去做私有化的直接原因。先说结论型的判断KylinWork 适合有部署能力的团队不适合只想在线调 API 的个人开发。它的价值不在模型效果本身而在把大模型推理、知识库检索、Agent 编排、工具调用全部收进企业可控环境并给业务系统提供标准接入方式。本文会按落地顺序拆解方案定位、架构分层、环境准备、部署启动、功能测试、接口与批量任务、资源占用观察、常见问题排查最后给一套企业落地建议。内容偏工程向全程围绕“怎么真正跑起来”展开。1. KylinWork 核心能力速览能力项说明方案类型企业级 AI Agent 私有化部署解决方案核心定位在内网或隔离环境完成大模型推理、Agent 编排、知识库问答与业务系统集成主要能力对话助手、RAG 知识库问答、工作流编排、工具调用、接口 API、批量任务部署方式以容器化交付为主通常在 Linux 服务器上通过 Docker Compose 或 K8s 启动硬件门槛纯 CPU 可做基础功能验证生产建议配备 NVIDIA GPU显存大小取决于模型规格模型接入以私有化开源模型为主可对接 Qwen、ChatGLM、DeepSeek 等系列模型具体以支持清单为准接口能力业务系统一般通过 HTTP API 接入包含鉴权与调用日志批量任务支持任务队列式批量处理具体队列与重试机制以实际版本为准适合场景金融、政企、制造、法律、医疗等对数据合规要求高的行业需要说明的是上表中的部分参数属于面向这类方案的通用判断。不同交付版本的镜像名、端口、环境变量、模型支持列表都会有差异实操前务必以官方文档或交付包里的说明为准不要拿公开信息直接套用。2. 适用场景与使用边界先讲清楚谁适合用。第一类是企业的 IT 或算法团队手里有业务系统和数据资产想在内部快速搭建一个“能回答问题、能调用内部工具、能跑批量任务”的 AI 助手第二类是系统集成商ISV需要把 Agent 能力嵌入 OA、CRM、ERP 或工单系统第三类是对文档处理有强需求的组织比如合同审查、制度问答、知识库检索这类场景用私有化 RAG 方案可以明显降低敏感信息外泄风险。这个方案能解决的核心问题有三个。一是数据合规企业内部文档、客户信息、财务报表不需要经过外部模型服务所有处理都发生在内网二是链路可控从用户提问、工具调用到模型返回每一步都能产生日志出问题时可以回溯三是成本可预算模型推理资源和 API 调用都跑在自有机房或云私有网络里使用量不再按 token 单价层层累计。也要说清楚不适合什么。个人开发者做原型验证直接用云端 API 显然更快、更便宜团队没有运维能力但想快速上线私有化部署的维护成本反而会拖慢进度对生成效果有极高要求但又不愿意投入 GPU 资源的组织私有化部署也很难达到预期。还有一个容易忽略的点私有化并不天然等于安全。如果权限配置松散、日志审计缺失、模型和数据授权不明确反而会出现新的风险敞口。涉及员工信息、客户隐私、版权素材、人脸声音等敏感数据时必须做好授权确认、脱敏处理和访问控制。3. 架构拆解可落地的私有化 AI Agent 需要哪些层从材料和使用经验看一个能稳定落地的私有化 AI Agent 方案至少需要拆成六层来看。分层不是为了好看而是为了出问题时能快速定位是模型推理挂了还是知识库检索错了还是工具调用超时。第一层是接入层。用户通过 Web 对话界面、IM 机器人或企业门户发消息外部系统通过 HTTP API 调用 Agent。接入层的职责是做统一入口、身份认证和流量分发避免每个业务系统直接连模型服务。第二层是 Agent 编排层。这里负责任务规划、意图识别、工具选择和多轮记忆管理。用户问“查一下这个月的订单异常”编排层要判断这个问题需不需要调用订单系统的接口如果需要就生成参数并触发调用。编排层的设计直接决定 Agent 的可用性目前主流做法是基于大模型的函数调用能力配合固定的工作流模板做兜底。第三层是模型推理层。这是资源消耗的大头包含主对话模型和 Embedding 模型。主对话模型负责生成和推理Embedding 模型负责把文本转成向量用于检索。推理层可以自己部署模型服务也可以对接已有的推理框架比如 vLLM、TGI 等具体以方案的兼容列表为准。第四层是知识库层。企业私有化部署免不了做 RAG这部分包含文档解析、切片、向量化、向量存储和检索重排序。文件格式多样化是常见痛点PDF、Word、Excel、扫描件都要能处理切片策略直接影响回答质量。第五层是工具与集成层。这是 Agent 真正产生业务价值的地方通过 HTTP 插件、数据库连接器、消息队列等方式让 Agent 调用内部 API。工具调用要做参数校验、超时控制和异常兜底否则一个接口抖动就会让整个任务失败。第六层是运维与安全层。包含日志收集、性能监控、权限管理、密钥管理和审计追溯。私有化部署上线后运维层决定这个系统能不能长期稳定跑下去很多项目死在“模型效果还行但没人敢上线”就是缺了这层。4. 环境准备与前置条件在动手部署之前先按下面的清单把环境检查一遍。环境准备不到位后面所有排错都是在浪费时间。检查项建议配置操作系统Ubuntu 20.04/22.04 或 CentOS 7x86_64 架构容器环境Docker 20.10docker-compose v2或 Kubernetes 1.24GPU 驱动使用 GPU 推理时需要 NVIDIA 驱动和 nvidia-container-toolkit内存32G 起步更稳妥纯 CPU 推理建议 64G 以上磁盘系统盘预留 50G模型目录按模型大小预留 50G 到 200G网络内网部署需提前确认能否访问镜像仓库离线环境要准备离线安装包如果你是离线内网环境有两件事要提前做。第一是容器镜像找一台可以访问外网的机器把镜像拉下来然后通过docker save导出成 tar 文件再在内网用docker load导入第二是模型文件建议通过国内可访问的模型社区渠道下载再按方案要求放到指定目录。不要把这两个环节放到部署当天才处理离线环境下传一个大模型文件的时间可能比部署本身还长。确认 GPU 是否可用可以执行下面两个命令# 查看 GPU 驱动是否正常 nvidia-smi # 查看 Docker 是否能识别 GPU docker info | grep -i runtime如果nvidia-smi正常但 Docker 无法使用 GPU通常是缺少 nvidia-container-toolkit需要单独安装并重启 Docker 服务。5. 安装部署与启动方式KylinWork 这类方案一般以容器化方式交付启动逻辑通常是“准备好镜像、模型和配置文件然后一条命令拉起全部服务”。下面给出一套通用的 docker-compose 模板镜像名、端口和环境变量都需要按实际交付包替换不要直接照抄。version: 3.8 services: gateway: image: kylinwork/gateway:latest ports: - 8080:8080 environment: - LOG_LEVELinfo depends_on: - agent-core restart: unless-stopped agent-core: image: kylinwork/agent-core:latest environment: - MODEL_ENDPOINThttp://model-server:8000/v1 - KNOWLEDGE_BASE_PATH/data/kb - TOOL_REGISTRY_ENDPOINThttp://tool-registry:9000 volumes: - ./config:/app/config - ./data:/data - ./logs:/app/logs depends_on: - model-server restart: unless-stopped model-server: image: kylinwork/model-server:latest volumes: - /data/models:/models deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] restart: unless-stopped启动和验证的基本命令如下# 建立工作目录按你自己的路径替换 mkdir -p /opt/kylinwork/{config,data,logs,models} # 把 docker-compose.yml 放到 /opt/kylinwork 后执行 cd /opt/kylinwork docker compose up -d # 查看服务状态 docker compose ps # 实时查看核心服务日志 docker compose logs -f agent-core # 健康检查端口以实际部署为准 curl http://127.0.0.1:8080/health启动后重点看三件事。第一所有容器是否都处于 running 状态第二模型服务日志里是否出现模型加载完成的关键字第三健康检查接口是否返回正常。三个条件都满足说明基础链路已经通了。如果某个容器反复重启不要急着删了重来先docker compose logs看具体报错大多数启动失败都是模型路径、端口冲突或环境变量写错导致的。6. 功能测试与效果验证部署成功只是开始真正要花时间的是功能验证。建议按照“基础对话、知识库问答、工具调用、工作流、批量任务”的顺序逐项测试每项都要明确输入、预期结果和失败排查方向。6.1 基础对话测试测试目的是确认模型推理链路是通的。输入一个简单问题比如“用一句话解释什么是 RAG”预期是模型正常返回文本服务日志没有报错。如果这一步就失败优先检查模型服务是否启动成功、模型文件路径是否正确、GPU 是否被容器识别。6.2 知识库 RAG 问答测试先准备一份测试文档内容要和正式业务相关但不要太长。上传文档后触发解析和切片再等待向量化完成。关键问题是能否引用文档中的具体内容回答。如果回答遗漏或编造重点检查切片粒度、检索 top-k 参数和重排序逻辑。一个常见错误是文档上传成功但向量化没有完成就开始提问结果检索不到内容这类问题要看任务队列日志。6.3 Agent 工具调用测试工具调用是私有化 AI Agent 和普通聊天的本质区别。建议准备一个简单的内部测试接口比如查询订单状态的模拟服务按工具注册格式配置好 schema然后输入“查询订单 2024001 的状态”。预期是 Agent 能正确识别意图、生成调用参数、调用接口并把结果整合成自然语言回复。如果工具调用失败从三个方向排查工具的 schema 描述是否准确模型本身是否具备较强的函数调用能力测试接口是否超时或返回异常格式。很多时候不是 Agent 的问题而是接口响应结构太复杂模型解析不了。6.4 批量任务测试批量任务用于验证系统在持续负载下的稳定性。准备一个包含 20 到 50 条问题的输入文件逐条跑记录成功数、失败数、单条耗时的分布。判断标准不是每条都成功而是失败的任务能否自动重试、能否从日志中定位失败原因。批量测试最能暴露问题比如连接池过小导致并发请求排队、某个工具接口被限流、长文本输入导致显存溢出等。7. 接口 API 调用示例私有化部署的最终目的通常是给业务系统提供能力API 接入是必测项。不同方案的接口风格不同但业界已经基本收敛到 OpenAI 兼容风格下面给出通用调用示例路径和鉴权方式需要按实际文档调整。curl -X POST http://127.0.0.1:8080/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer ${API_KEY} \ -d { messages: [ {role: user, content: 请总结这份合同中的违约责任条款} ], session_id: test-session-001, stream: false }Python 调用示例同样保留通用结构注意超时时间要给足。私有化模型推理速度通常慢于云端大模型 API超时设置 60 到 120 秒比较稳妥。import requests import time API_URL http://127.0.0.1:8080/api/v1/chat/completions API_KEY your-api-key def ask_agent(content, session_iddefault): payload { messages: [{role: user, content: content}], session_id: session_id, stream: False, } resp requests.post( API_URL, jsonpayload, headers{Authorization: fBearer {API_KEY}}, timeout120, ) resp.raise_for_status() return resp.json() if __name__ __main__: questions [ 第一个测试问题, 第二个测试问题, ] for i, q in enumerate(questions, 1): start time.time() try: result ask_agent(q, session_idfbatch-{i}) content result[choices][0][message][content] print(f问题{i}完成耗时{time.time() - start:.2f}s) except Exception as e: print(f问题{i}失败: {e})批量任务的工程化建议输入文件、输出结果、失败日志分别放不同目录每条任务记录开始时间、结束时间、状态和错误信息失败任务先重试一次仍然失败则进入死信队列等人工排查。不要把批量任务做成“一条 for 循环直接压过去”没有日志和重试机制的批量任务在生产环境里会很难收场。8. 资源占用与性能观察私有化部署上线前必须对资源占用有底。观察手段是两条命令GPU 用nvidia-smi看显存和利用率容器整体用docker stats看 CPU 和内存。# 实时查看 GPU 显存和利用率 nvidia-smi --query-gpuindex,memory.used,utilization.gpu --formatcsv -l 1 # 查看所有容器资源占用 docker stats --format table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}性能影响的主要因素是模型参数规模、上下文长度、单次请求的 max_tokens、并发数和向量库检索量。上下文越长、max_tokens 越大显存占用和首字延迟都会明显上升并发数翻倍显存占用不一定线性翻倍因为推理服务会做批处理但超过上限就会 OOM。这些参数需要按实际模型和硬件组合测试不存在一套通用的“推荐显存数字”。降低资源占用的常见手段包括对模型做 INT8 或 4bit 量化前提是推理框架支持并且接受精度损失限制单请求的 max_tokens防止长文本生成拖垮整体吞吐给推理服务配置批处理参数提高 GPU 利用率不用推理时把 Embedding 模型和主模型拆分部署避免互相抢占显存。另外要提醒一点纯 CPU 推理可以跑通功能但并发场景下延迟会非常高如果业务对响应时间有要求生产环境不要指望 CPU 硬扛。9. 常见问题与排查方法问题现象可能原因排查方式解决方案容器启动后立刻退出端口被占用、配置缺失、镜像不存在查看docker compose logs更换端口补齐配置确认镜像名模型加载失败模型路径不对、格式不兼容、磁盘不足检查模型目录和推理日志按文档放置模型文件预留足够磁盘Docker 无法使用 GPU缺少 nvidia-container-toolkit执行nvidia-smi和docker info安装 toolkit 并重启 Docker推理时报显存不足并发过高或模型超过显存容量观察nvidia-smi的 memory.used降低并发启用量化换小模型内网拉取镜像失败无法访问外网镜像仓库查看拉取日志外网机器docker save导出内网docker load导入API 调用超时推理时间过长、连接池太小查看调用日志和推理延迟调大超时时间增加连接池限制 max_tokens批量任务卡住单条任务异常导致队列阻塞查看任务状态和日志增加超时熔断和失败重试机制回答质量不稳定提示词、切片策略或采样参数问题固定参数对比测试优化提示词调整切片和 temperature知识库检索不到内容向量化未完成或切片过小查看向量化任务日志等待任务完成调整切片长度和 top-k工具调用频繁失败接口 schema 不准或接口本身异常单独测试工具接口修正 schema简化接口返回结构排错的总原则是先看日志再做操作。不要一上来就重启服务很多问题在日志里已经有明确答案。建议部署时就把日志目录挂载出来并配置轮转否则日志文件越来越大排错时反而找不到定位点。10. 安全合规与最佳实践企业私有化部署 AI Agent安全这块必须前置考虑不能上线后再补。第一是网络隔离Agent 服务、模型服务、知识库存储尽量放在内网区域业务系统通过网关接入不要直接把模型服务暴露到公网。第二是访问控制API 必须带鉴权密钥用专门的密钥管理系统保存不要写死在配置文件和代码里。第三是日志审计每次请求要记录调用人、时间、输入内容、工具调用和输出结果出现问题时能完整回溯。数据处理层面要注意三点输入数据先做敏感信息识别和脱敏尤其是涉及个人隐私和企业机密的内容知识库文档引入前确认版权和授权不要把未授权的扫描件、第三方资料直接灌进向量库生成结果在涉及合同、医疗、金融等高风险场景时必须加入人工复核环节不能让 Agent 的输出直接进入业务决策流程。工程化方面推荐坚持几个习惯。第一次部署先用最小参数跑通再逐步放开并发和功能保留一套最小可运行配置作为排查问题的基准环境模型文件、输入素材、输出结果分目录管理不要堆在一起批量任务必须加日志、重试和死信队列接口服务要限制访问范围和调用频率。这套习惯能显著降低上线后的维护成本。11. 总结与下一步KylinWork 这类方案最值得尝试的点是把“私有化模型 知识库 Agent 编排 业务工具调用”做成了一条相对完整的链路。相比自己从零拼装用现成方案可以节省大量集成时间尤其适合本身就有内网服务器和数据资产的企业。拿到方案后最先应该验证的是三条链路基础对话是否畅通、知识库问答是否引用正确、工具调用是否稳定。这三条通了核心价值就已经体现出来。最容易踩的坑集中在环境准备阶段离线环境的镜像和模型文件没有提前准备好、GPU 容器运行时没有配置、模型与推理框架版本不匹配。这几个坑都有一个共同特征就是部署当天才发现而解决起来又特别耗时。后续可以扩展的方向不少接入多个模型做路由和切换按任务难度分配不同规格的模型把批量任务接入消息队列支持分布式并行调度将 Agent 技能模块化形成企业内部可复用的技能市场再往后就是把整套服务迁到 K8s利用弹性伸缩应对业务高峰。建议先把基础链路跑稳再逐步做工程化升级。