VeapAI 自然语言操作实战｜第 08 篇：治理层——审计、指标、评估与权限

> 系列：VeapAI 自然语言操作实战（全体系架构专题）

> 本文要点：五本审计账 · 三个运营指标 · 一套评估体系 · 一道权限闸

系统跑起来之后，靠什么回答"用得怎么样"

前面七篇讲了数据怎么进来、知识怎么加工、命令怎么执行。但管理者会问四个问题：

答不上来的问题多不多？哪里缺知识？
检索准不准？有没有把错的资料喂给模型？
执行出错时，能不能从页面一路追到具体节点？
一份敏感资料，谁能看？谁不能看？

这四个问题对应治理层的四件事：审计、指标、评估、权限。

! $治理层总览：审计多源、运营指标、评估体系、权限治理与稳定契约$

审计：五本账，各记各的

治理不是事后补日志，而是每一层做事时同时留痕。全平台有五本审计账：

执行审计：agent 的 start / finish / terminate / error 四态，由唯一写入点落库；
服务调用日志：每次服务调用的成功与失败，含请求响应摘要；
语义转换日志：逐行状态、失败原因、触发类型------批量转换时能精确到"哪一行没转成"；
检索审计：耗时、结果数、过滤参数；查询向量只落 hash，不落原文；
运维操作日志：Milvus 等组件的操作留痕。

五本账的共同原则是：错误信息必须可读，敏感信息必须不可读。密钥、认证信息在落库前一律打码------审计是给排障用的，不是给泄露用的。

指标：三个口径，写死在代码里

! $运营看板：无答案率、召回命中率、知识覆盖率与补录任务$

运营看板上只有三个核心指标，但每个的口径都在实现里写死：

无答案率：答案为空、或标注了"需补充"的问题占比------分子分母怎么算，代码说了算；
召回命中率：有结果的检索占比；无结果计入分母，取数失败（null）不计入；
知识覆盖率：被回答引用的知识条目去重计数，由服务端解析引用明细后统计。

指标不开放给各处"口头定义"，是因为口径一旦漂移，看板就失去意义。同一份数据，说清楚口径之后再讨论治理动作。

指标指向一个动作：补录。无答案的问题会被沉淀成补录任务，走 todo / doing / done / closed 四个状态，由运营侧认领、补资料、关闭。指标不是摆设，它连着任务流。

评估：不写生产业务表

! $评估报告：逐案明细、四指标打分与复核状态$

评估体系回答"检索与回答的质量有没有退步"，由四张表驱动：

数据集与用例：问题、期望答案、期望引用；
运行：一次批量执行，状态机是 running → success / fail；
逐案结果：每题四条启发式指标的得分，加上断言与人工复核（pending / passed / rejected）。

四条指标通过 SPI 扩展：召回覆盖、召回精度、忠实度、相关性。默认实现是启发式的，可以按业务替换成更严格的判定。报告直接在下钻页面查看，逐案明细与汇总一目了然。

一条硬性边界：评估只读生产数据、只写评估自己的表。它绝不往生产业务表里写东西，需要补的数据走补录任务流------评估与运营通过任务交接，而不是通过数据库互写。

权限：召回时的最后一道闸

权限治理要解决"谁能看到哪份知识"。核心是一张 ACL 表：对象（主题 / 条目 / 文档）× 主体（用户 / 角色 / 组 / 部门）× 允许或拒绝。

! $权限矩阵：以对象为主体维度的 ACL 配置界面$

判定语义有四条，缺一不可：

对象没有任何主体限制 → 全可见；
对象没有任何 ACL 记录 → 默认可见；
拒绝命中 → 过滤，哪怕同时存在允许；
存在允许清单但未命中 → 过滤。

第四条最容易踩：一旦给某个对象配置了任何一条"允许"，这个对象就进入了白名单模式------没被点名的用户全部失去可见性。这是刻意的：显式授权即收窄范围。

权限过滤挂在召回链路上：在打分之后、重排之前执行，主题级与条目级两道过滤连续生效。主体聚合走来源接口（SPI）：内置实现覆盖用户与角色，外部目录（LDAP、OAuth2、OIDC）按同一接口预留扩展位。

源码走读

运营与评估：`veap-cloud/veap-modules/veap-ai` 下的运营指标与评估模块，落到 `ai_qa_eval_*` 系列表与评估报告接口；
权限：`veap-cloud/veap-modules/veap-ai` 的 ACL 模块------记录读取、主体聚合、过滤解析三段式；数据表为 `ai_knowledge_acl`；
前端：运营看板视图 `/qaOpsDashboard`，评估入口与权限矩阵都在 AiConsole 的治理分组下。

较真：两个容易被略过的语义

第一个：审计里的密钥打码。运维操作日志最初的实现把请求体原样存了下来，其中包含数据源连接信息。排查需求没问题，但密码也进了日志表。修复方式是在写入前统一打码，认证类字段替换为固定掩码------日志可读性与密钥安全，只能选后者优先。

第二个：ACL 的"首次授权即白名单"。上线初期按"没有记录就可见"理解，给一个部门配了主题授权后发现，其他部门反而看不到了------他们本来也没有记录，期望是可见。这不是 bug，是第四条语义生效了：存在允许清单但未命中即过滤。把这个语义写进配置页提示文案后，误解消失。凡是与直觉相反但合理的语义，都要在界面上说清楚。

复现与验证

看板：进入 `/qaOpsDashboard`，核对三个指标与补录任务列表；
跑评估：选一个数据集发起一次运行，等状态变为 success 后看逐案得分与复核入口；
验权限：给一个知识主题配置一个用户允许，用另一个用户检索，确认被过滤；删除全部记录，确认恢复可见；
查审计：`SELECT log_type FROM ai_agent_instance_log ORDER BY id DESC LIMIT 10;` 观察四态写入。

治理层到此收束：每层做事留痕、指标口径固化、评估与生产隔离、召回有闸。最后要做的，是把这一路的设计共识提炼成可以带走的原则，以及看看这套体系往哪里长。