系列VeapAI 自然语言操作实战全体系架构专题 本文要点语义模板五步执行 · 4 个稳定字段 · 触发三态 · 目录资源预构建的两步铁律## 最准的知识系统自己就有上一篇讲的是附件外部资料进系统先解析、再拆条。这一篇讲另一类素材——系统自身。用户说给张三授权用户查询功能模型需要知道系统里有哪些表、哪些接口可以授权、字典里的启用对应什么值。这些事实不在任何文档里而是散落在数据字典、代码生成器、业务字典三处。请人整理成知识库不是不行是三天就过期。表结构改一次、字典加一项手工整理的清单就落后了。这套体系的做法是写一条 SQL 把系统元数据取出来渲染成知识条目。加工机叫语义模板semantic template本文只看它在这条链上的用法。## 一次执行五步走完![语义模板引擎触发三态、执行五步与稳定契约]一次模板执行固定五步全部由确定性代码编排1. 取数执行 fetch_rule 里的 SQL。只允许 SELECT系统会自动把 SQL 外包一层分页所以脚本里不许自带 LIMIT、OFFSET 和结尾分号2. 行解析按 parse_rule 的字段映射把结果集整理成标准行3. 变量装配行字段 variable_schema 声明的必填与可选变量逐个装进渲染上下文4. 渲染用 template_body 把每一行渲染成一段正文5. upsert按唯一键 topic_id business_id 写入知识条目。重复执行不产生重复条目。这里有一组必须背下来的字段。每行取数结果里必须包含 4 个稳定字段缺一个就报错| 稳定字段 | 用途 | 目录任务的取值 || --- | --- | --- || businessId | upsert 唯一键的另一半 | 表主键 / 字典主键 || sourceType | 溯源类型 | dictTable / dictType || sourceInfo | 溯源详情 | 同主键 || title | 条目标题 | 表标题 / 字典标题 |为什么把字段卡这么死因为这一行是什么必须有唯一答案。businessId 负责去重sourceType 与 sourceInfo 负责追根溯源title 负责给人看。四个字段一缺这条知识在后面的检索、审计里都会成为孤儿。执行过程逐行留痕。ai_semantic_transform_log 记录三个关键字段状态待处理 / 处理中 / 成功 / 失败、失败原因、触发类型。行失败不静默跳过报错里带上 businessId知道该去查哪一行。![语义模板配置取数规则、变量定义与模板正文都在这里维护]## 渲染与空值一个口径说了算模板正文支持占位符和条件语法。有没有值直接决定一段话怎么写- 变量缺失且非必填 → 替换为空串标签和内容一起消失不留噪点- 必填变量缺失 → 用户可修复错误明确告诉你是哪个变量- 值是纯空白 → 与空值同处理。这三条口径的背后是一次返工。早期执行、校验、预览三个地方对空值的判定不一致。执行时认为纯空白可以保留校验却按有值放行预览又把它当未解析变量标红。同一个模板三个地方三种答案。修法是收敛到同一个判定实现hasText 口径执行、校验、预览共用。经验写在这里凡是空这个概念全链路只能有一种解释。预览还有一个顺手的设计模板里出现未解析变量时会直接标出来不用等执行失败才发现变量名拼错了。![语义转换日志每一行的执行结果与失败原因都可追溯]## 触发手动、事件、定时各走各的门模板的触发模式有三种取值主动manual、被动passive、混合mixed。对应的入口也是三个- 手动执行管理页或接口触发- 事件触发内网入口 POST /ai/inner/semanticTemplate/executeByEventType?eventType...按事件类型精确匹配模板没有匹配就返回无匹配模板不做推断- 定时执行模板级入口要求 status1 且 schedule_cron 非空。定时表达式在保存时就要过校验必须是合法的 6 段 cron秒 分 时 日 月 周非法直接报用户可修复错误。schedule_cron 被定义为期望调度表达式的唯一事实来源实际调度由定时任务按这个值发起。## 目录资源预构建三个任务一根铁律把镜头拉回总览图里的全局语义命令。它运行时要看三份目录表目录、表关系、字典翻译。这三份都不是运行时现查的而是离线预构建的上下文资源。![目录资源预构建链三个任务、执行与同步两步、以及挂载点]三个任务全部取材系统自身的元数据| 任务 | 知识主题 code | 取数来源 | 渲染格式 || --- | --- | --- | --- || 表目录 | agent.globalCmd.catalog | 数据表字典status1、del_state0按 sort 排序 | 表编码 竖线 表标题 || 表关系 | agent.globalCmd.relations | 同表追加主键非空过滤 | 表编码 竖线 表标题 竖线 主键 竖线 标题字段 || 字典翻译 | agent.globalCmd.dictMap | 业务字典选项启用、标题非空按字典分组 | 字典标题 选项「标签→值」 |构建分两步而且必须连续执行1. 执行跑三个语义模板把系统元数据渲染成知识条目2. 同步把知识主题同步成上下文资源res_key 就是主题 code条目正文按序合并。之后 LLM-B表定位静态挂载表目录与表关系LLM-C执行计划静态挂载字典翻译。运行期只读资源禁止在运行期重建。![上下文资源主题同步后的资源内容等待被 LLM 节点静态注入]## 源码走读- 执行引擎veap-cloud/veap-modules/veap-ai 的 AiSemanticTemplateExecuteService——executeByEventTypeOrThrow事件、executeByTemplateIdOrThrow模板级定时、upsertKnowledgeEntryOrThrow写入与 4 稳定字段校验- 保存校验AiSemanticTemplateValidationService——cron 合法性等写侧校验- 内网入口InnerAiSemanticTemplateController事件与模板级定时- 资源同步AiAppContextResourceKnowledgeSyncAppService——主题 → 资源res_key 主题 code正文按序合并- 前端加工台veap-ui/src/components/AiConsole/mods/semanticTemplateGen渲染器家族simple / placeholder / text 三种语法码共用同一套占位符实现。## 较真两次只做了一半的返工这一篇的两个坑本质上是同一种错误对称性破了。第一次是代码只改了一半。模板执行后知识主题页显示的正文没更新。排查发现写入逻辑在 upsert 时新增分支写了 content更新分支却只写了 semantic_content 和元数据。展示端读的是 content自然看到旧值。修复很直接更新分支补上 content两个分支字段对齐。从那次起我们把upsert 两个分支字段必须对称写成了硬约束。审计方式也很具体以页面展示字段为锚逐字段比对两个分支。第二次是运维只做了一半。有一轮测试分析近 30 天登录活跃趋势突然报命令可定位到多个数据表。查下去发现表字典里一张表已经清理条目侧也重建了。但资源侧还停着几天前的快照已删除的表仍留在 LLM 的注入内容里。模型定位时自然撞了重名。处置是把资源同步重跑一遍并立下规矩执行与同步必须连续只做一半等于没做。后来的巡检会专门断言资源块集合 条目集合防的就是清而不生效。## 复现与验证1. 看模板SELECT code, template_code, trigger_mode, schedule_cron FROM ai_semantic_template WHERE code globalCmdCatalog;2. 执行一次调 POST /ai/semanticTemplate/execute传 templateId再查 SELECT code, title FROM ai_knowledge_entry WHERE topic_id 主题id;确认条目按渲染格式生成3. 看留痕SELECT status, trigger_type, fail_reason FROM ai_semantic_transform_log WHERE template_id 模板id ORDER BY id DESC LIMIT 5;4. 看资源SELECT res_key, LEFT(content_text, 60) FROM ai_app_context_resource WHERE res_key agent.globalCmd.catalog;一个边界要说清楚不是所有东西都适合静态化成资源。冻结进资源的必须同时满足平台级静态事实和没有脚本校验依赖两个条件。字段清单和接口清单依赖运行时的目标表就留在运行期拉取——静态化是优化不是默认。系统数据吃完之后知识版图基本齐了一份来自附件一份来自系统自身。接下来轮到那条能被计算的路径把知识条目变成向量。