1. 从“开发态”到“发布态”AI 助手为什么值得单独拎出来讲最近在做三维可视化项目交付时遇到一个很典型的场景开发环境里通过 CIMPro 给场景配好了数据、写好了交互逻辑也把“AI 助手”调试得能回答项目相关的问题。可是一旦项目进入“发布态”也就是交付给甲方、部署到现场服务器之后AI 助手要么不弹窗要么问答答非所问要么命令按钮点了没反应。排查一圈后发现问题大多不是功能本身开发错了而是对 CIMPro 的“开发态”和“发布态”两种运行模式理解不到位。AI 助手在开发态里跑得通不代表发布态里就能直接工作它涉及知识库路径、业务动作绑定、模型服务地址、权限配置、网络策略等一系列和“发布环境”强相关的设置。本文将围绕 CIMPro 发布态中的 AI 助手使用从概念、能力拆解、配置流程、集成实操、常见报错到工程化建议完整梳理一套可以照着落地的方案。适合正在使用 CIMPro 做数字孪生项目交付的开发者也适合负责项目部署实施、需要把 AI 助手从开发环境迁到生产环境的同学阅读。2. 先搞懂CIMPro 是什么开发态和发布态差在哪2.1 CIMPro 的定位CIMPro 是一款面向数字孪生场景的零代码/低代码开发平台常用于智慧城市、智慧园区、工业孪生、水利调度、交通可视化等项目的场景搭建。它把三维场景、数据接入、业务交互、可视化组件等能力封装成可视化操作方式让实施人员不需要从零手写 WebGL 或 Three.js 渲染逻辑也能快速构建一个可交互的孪生场景。在 CIMPro 中一个完整的应用通常会包含三维场景模型、地形、标注、特效数据接入实时数据、历史数据、接口数据业务交互点击、弹窗、图层显隐、相机飞行页面集成把场景嵌入到已有的业务系统中AI 助手自然语言问答、场景指令控制、数据检索。2.2 开发态与发布态的区别这是本文最核心的概念先直接对比对比项开发态发布态运行目的项目编辑、调试、效果验证交付给最终用户使用访问方式CIMPro 编辑器内部预览或调试地址独立部署的访问地址数据源常连开发数据库、测试接口必须切换为生产数据源AI 助手配置可调模型服务、知识库可临时修改配置需要固化路径可访问权限控制偏向放开便于调试需要按角色、按项目隔离网络环境本机或内网默认可访问外网生产环境网络受限需提前验证很多项目的 AI 助手在开发态表现良好到了发布态就失效根本原因就是“开发态默认能连通的东西发布态不一定能连通”。例如开发态里模型服务用 localhost发布态部署到服务器后 localhost 指向的可能就不是同一台服务了。2.3 发布态 AI 助手的本质CIMPro 发布态的 AI 助手本质上仍然是一个“前端界面 后端服务 模型服务 知识库”的组合。CIMPro 负责提供助手对话界面、把用户输入转发给模型处理、再把模型输出渲染到界面上。因此要让 AI 助手在发布态稳定可用核心是保证这四层在目标环境都正常工作前端界面能正常加载后端接口能鉴权通过并转发请求模型服务可能是云端大模型 API也可能是本地私有大模型能被访问知识库和业务动作绑定关系已固化到发布数据中。3. 发布态 AI 助手有哪些核心能力在进入配置操作之前先搞清楚 CIMPro 的 AI 助手在发布态能做什么这样才能按照项目需求去设计功能边界。3.1 自然语言问答用户可以在对话窗口输入中文问题例如“当前园区有多少个摄像头在线”“3 号楼的能耗数据是多少”“昨天设备告警总数是多少”CIMPro 的 AI 助手将问题转化为数据查询或知识库检索再返回结果。发布态下需要保证知识库内容已上传并发布、数据接口已替换为生产地址、模型服务能正常响应。3.2 场景指令控制AI 助手不只是“聊天机器人”它还可以联动 CIMPro 场景能力例如“切换到设备分布视角”“定位到 3 号楼主入口”“显示告警设备”“隐藏楼宇标注”这类能力在开发态很好用但在发布态容易出问题原因是“指令动作”绑定的是开发态场景中的对象和图层 ID发布态如果场景资源有变更指令就找不到目标。3.3 数据检索与指标问答结合接入的实时数据库或业务 APIAI 助手可以回答具体指标例如“A 区当前人流量”“B 栋当前温度”。发布态下数据通道的连通性、数据刷新频率、鉴权方式都必须按生产环境做重新验证。3.4 业务知识库问答可以把项目手册、运维文档、应急预案等上传到知识库AI 助手基于知识库做检索增强问答。这类功能对发布态的网络依赖相对较低但要注意知识库文件在发布包中是否正确包含、路径是否有中文或空格、权限是否只读。4. 发布态 AI 助手配置流程实操下面按完整流程拆解 CIMPro 发布态 AI 助手的配置步骤。由于不同版本 CIMPro 的界面可能存在差异本文以通用配置思路为主线操作项名称以你当前版本为准但配置逻辑一致。4.1 检查项目运行环境进入发布态之前先确认服务器和浏览器环境满足以下要求环境项建议要求操作系统Windows Server 2016 及以上 / Linux按版本要求浏览器Chrome、Edge 较新版本建议双核模式网络能访问模型服务地址能访问生产数据接口权限安装目录可读写、日志目录可写入部署方式独立部署或嵌入已有系统如果项目交付环境无法访问外网需要提前确认是否使用局域网私有化模型服务或者是否允许开放指定域名白名单。4.2 创建并配置 AI 助手在 CIMPro 项目中找到 AI 助手或智能助手配置入口新建一个助手实例。关键配置项如下{ assistantName: 园区智能助手, description: 回答园区设备、能耗、告警相关问题支持场景定位, model: qwen-plus, temperature: 0.3, maxTokens: 2048, enableScenarioCommand: true, enableDataQuery: true, enableKnowledgeBase: true }参数说明assistantName助手名称会显示在对话窗口标题中。model模型服务标识根据你的模型服务商或私有化部署情况填写。temperature控制回答随机性建议 0.2~0.5避免回答太发散。maxTokens单次回答的最大长度。enableScenarioCommand是否开启场景指令控制如果不需要可以关闭减少发布态的调试成本。enableDataQuery是否允许助手查询业务数据。enableKnowledgeBase是否启用知识库检索。这里要注意不要为了功能丰富把所有开关都打开。发布态追求稳定每一项能力都对应一组依赖建议按实际业务需要开启。4.3 配置模型服务地址模型服务是 AI 助手的“大脑”发布态下常见的模型接入方式有两种方式一云端大模型 API使用公共场所云模型 API 时配置重点是地址、密钥和超时时间。以 OpenAI 兼容接口为例model: apiType: openai-compatible baseUrl: https://api.example.com/v1 apiKey: ${MODEL_API_KEY} modelName: qwen-plus timeout: 30生产环境建议不要把apiKey明文写死在项目中通过环境变量或部署配置注入密钥出口网络只放行模型服务域名。方式二私有化部署模型服务如果项目要求数据不出内网可以使用私有化模型服务例如基于 vLLM、Ollama 等方式部署的本地模型。配置上把baseUrl指向内网服务地址model: apiType: openai-compatible baseUrl: http://192.168.1.100:8000/v1 apiKey: sk-local modelName: local-llm timeout: 60私有化模型在发布态的调试重点通常是GPU 显存是否足够、并发是否支持、容不宽容错。建议在交付前做一轮简单的并发压测。4.4 配置知识库AI 助手的知识库问答能力依赖知识库的发布状态。以文档问答为例需要把项目资料整理成知识库文件并在发布态确认知识库数据已加载。知识库文件格式建议文本类.txt、.md、.pdf表格类.csv、.xlsx字段尽量简单避免合并单元格单文件大小不要过大建议拆分配置完成后建议在开发态先用几组测试问题验证检索效果。例如上传园区应急预案后测试“火灾发生时如何疏散”是否能检索到对应文档内容。提示发布态部署后知识库文件是随项目包一起发布的修改知识库内容需要重新发布或通过后台热更新。如果项目支持热更新要确认更新后是否需要重启服务。4.5 绑定场景指令AI 助手要控制三维场景需要把“自然语言意图”映射到“场景动作”上。在配置界面中通常需要定义指令名称例如“定位到主入口”绑定场景相机位置或视角绑定图层、标注、特效的显隐设置触发关键词例如“飞到”“定位到”“切换视角”。配置完成后在开发态测试以下场景输入“定位到主入口”场景是否切换到目标视角输入“显示告警设备”告警图层是否显示输入“还原视角”场景是否回到初始状态。发布态中如果指令失效优先检查场景资源引用关系是否完整以及发布包中是否包含对应的模型和图层资源。4.6 发布前自检清单在点击“发布”之前建议按下面清单逐项确认检查项操作模型服务地址确认能从发布环境访问可以执行连通性测试密钥安全确认密钥已通过环境变量注入未硬编码知识库文件确认文件路径正确、命名无中文空格数据接口确认生产接口已配置CORS 策略允许访问场景指令确认指令绑定的对象、图层、视角存在权限配置确认哪些角色可以使用 AI 助手日志输出确认日志目录可写便于排查线上问题5. 发布态 AI 助手的集成与交互方式除了在 CIMPro 自带的场景页面里使用 AI 助手很多项目还需要把 AI 助手嵌入到已有的业务管理系统中。下面介绍两种常见的集成思路。5.1 页面内嵌模式如果 AI 助手界面以组件方式提供可以直接嵌到业务系统页面中类似嵌入一个聊天窗口。这种模式下对话界面、消息渲染都由 CIMPro 侧控制业务系统只需提供一个承载容器。前端嵌入示例思路参考div idcimpro-assistant-container stylewidth: 380px; height: 560px;/div script const assistant window.CIMProAssistant.init({ container: #cimpro-assistant-container, serverUrl: https://your-domain.com/assistant-api, token: getTokenFromBusinessSystem(), projectId: your-project-id, theme: light }); /script这个模式的好处是开发工作量小坏处是定制化程度有限。生产环境集成时需要提前确认serverUrl、token、projectId的获取方式和有效期。5.2 API 模式如果业务系统需要自定义对话界面只复用 AI 助手背后的问答能力可以通过 API 方式调用。以 HTTP 接口为例请求结构一般是{ sessionId: abc-123, message: 3号楼今天能耗是多少, userId: u_001, projectId: proj_001 }返回结构通常包含助手回复文本、命中的知识库片段、场景指令参数等。接入前要重点确认接口鉴权方式Token、签名、OAuth2会话状态如何保持服务端保存还是客户端传 sessionId接口超时时间特殊字符转义消息内容含引号、换行、HTML 标签。API 模式更适合定制化高、交互体验要求高的项目但开发工作量也更大需要业务系统自己处理对话气泡、加载态、错误提示等界面细节。5.3 发布态集成常见数据流从整体上看发布态 AI 助手的请求链路如下用户输入 → 业务系统页面 / CIMPro 场景页面 → AI 助手接口 → 鉴权校验 → 意图识别 → 场景指令 / 数据查询 / 知识库检索 → 调用大模型生成回答 → 返回前端渲染链路越长出问题的环节就越多。发布态排查问题时建议按这个链路从上往下逐段确认页面有没有发起请求 → 接口有没有收到请求 → 鉴权有没有通过 → 模型有没有返回 → 前端有没有正常渲染。6. 常见问题与排查思路发布态 AI 助手的问题千奇百怪但归纳下来大多集中在以下几类。6.1 AI 助手不显示或打不开问题现象常见原因解决思路发布后找不到 AI 助手入口发布配置中未启用助手功能进入项目配置确认 AI 助手开关已打开页面打开但对话窗口空白前端资源加载失败检查发布包是否完整F12 看控制台报错只有管理员能看到助手角色权限未配置在权限配置中为普通用户分配助手使用权限6.2 问答超时或无响应问题现象常见原因解决思路输入问题后一直转圈模型服务不可达服务器上执行 curl 测试模型接口连通性报 401/403 错误密钥失效或未注入环境变量检查密钥配置确认部署环境变量已加载响应很慢模型并发压力大或 prompt 过长降低 maxTokens、加长超时时间、减少知识库检索量一个很实用的排查命令在发布服务器上直接调用模型接口确认模型服务本身可用。curl -X POST http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: local-llm, messages: [{role: user, content: 你好}], max_tokens: 50 }如果返回正常问题大概率出在 CIMPro 侧配置如果返回超时或连接拒绝要先解决模型服务访问问题。6.3 回答内容答非所问问题现象常见原因解决思路回答与项目知识无关知识库未发布或未启用检查知识库状态重新上传并发布答非所问且内容发散temperature 设置过高调低 temperature例如 0.1~0.3数值问题回答错误数据接口鉴权失败或查询条件缺失检查数据查询接口日志确认查询参数和权限总是回答“我不知道”Prompt 引导不足或知识库未命中优化 Prompt 模板调整知识库切片策略6.4 场景指令不生效问题现象常见原因解决思路点击指令按钮无反应场景指令绑定的对象在发布包中不存在重新检查指令绑定确保对象存在指令触发但视角不对相机参数配置错误在开发态重新设置视角并发布更新指令经常识别错用户说法和触发词差别太大增加触发词或改用按钮方式触发固定指令场景指令类功能在发布态建议提供“指令按钮 对话指令”双重入口。按钮触发稳定可靠对话指令提供灵活性两者互补。实际项目交付中依赖纯自然语言控制场景的体验并不可控按钮兜底能显著降低交付风险。6.5 发布态排查通用思路如果 AI 助手在发布态出现问题按下面顺序排查通常比漫无目的地改配置更快打开浏览器开发者工具看 Network 请求有没有报错看接口返回码判断是前端问题、接口问题还是服务问题看 CIMPro 侧日志或部署服务日志定位到具体错误直接测试依赖项模型服务、数据接口、知识库连通性检查发布包是否需要重新发布检查服务器时间、时区、SSL 证书是否正常。7. 发布态 AI 助手的最佳实践与工程建议7.1 安全与密钥管理AI 助手会调用大模型 API也会访问业务数据接口因此安全是发布态的第一优先级。不要在项目文件中明文存放模型 API Key使用环境变量或配置中心管理密钥生产环境关闭调试模式避免错误信息泄露内部接口AI 助手接口本身要加鉴权不能裸奔在公网对用户输入做长度限制和内容过滤防止恶意超长输入打满模型上下文涉及业务数据时按最小权限原则配置数据接口权限。7.2 配置管理发布态的 AI 助手配置应视为“生产配置”不能随便改动。所有配置项记录在项目配置文档中变更配置前在开发态验证重要配置修改前备份原配置发布版本打标签方便回滚把模型参数、知识库版本、数据接口地址作为发布记录的一部分。7.3 日志与监控AI 助手类功能往往黑盒化程度高日志和监控是线上排错的“眼睛”。建议至少记录以下日志请求时间、用户 ID、会话 ID用户输入内容注意脱敏模型服务调用耗时和返回状态知识库检索是否命中场景指令是否匹配成功异常堆栈和错误码。对高频错误做监控告警例如模型接口连续 5 次超时就触发告警通知。7.4 知识库维护知识库内容会随项目运维更新发布态要有明确的更新流程。建立知识库文件版本管理上传新文档后必须重新验证问答效果知识库更新后通知相关人员重新测试关键问题对过期文档及时清理避免旧信息干扰回答知识库文件命名规范化不要使用带空格或中文括号的文件名。7.5 场景指令设计场景指令是 AI 助手中与三维场景最紧密的部分也是最容易出现版本不一致的部分。指令命名尽量统一例如“定位_xxx”“显示_xxx”“隐藏_xxx”触发词与场景对象名称保持一致指令绑定完成前先发布一次完整场景包并验证如果场景模型后续调整必须同步检查 AI 指令绑定是否失效。7.6 性能优化发布态 AI 助手的响应速度直接影响用户体验可以从几个方向优化模型服务侧开启流式输出让用户边等边看到内容知识库侧控制检索返回的文档片段数量接口侧增加缓存对高频问题使用预设回答前端侧对话数据分页加载避免一次性渲染大量消息造成卡顿。8. 总结与进一步学习方向本文从 CIMPro 的“开发态”和“发布态”差异讲起拆解了 AI 助手在发布态的核心能力和配置流程覆盖了模型服务配置、知识库发布、场景指令绑定、页面集成、常见排错和工程化建议。关键点可以归纳为三句话发布态不是“开发态的复制”而是要重新验证模型、数据、知识库、权限、网络整条链路AI 助手的稳定性问题绝大多数不是模型“笨”而是依赖项在生产环境没有打通发布前做好自检清单发布后做好日志监控能省掉大量现场排查时间。如果接下来想深入可以从这几个方向继续学习大模型 API 鉴权与限流策略、RAG 检索增强的知识库调优、私有化大模型部署与并发优化、CIMPro 场景指令与业务系统的深度联动。建议找一个小型园区或楼宇项目把 AI 助手的问答、场景指令、知识库三个能力完整走通一遍再逐步扩展到更复杂的业务流程。实际项目交付时还有一点值得特别留意AI 助手这类功能的用户预期往往很高但现场的模型能力、知识库质量和数据质量不一定能支撑所有问题。交付前要和需求方对齐“AI 助手能做什么、不能做什么”并配置好兜底话术和人工转接方式避免用户把 AI 助手当成全能客服最后影响项目验收效果。