AI 功能
AI 功能
ZRAdmin 内置三块 AI 能力：AI 对话助手、AI 用量统计、AI 访问治理。本文按「普通用户怎么用 → 管理员怎么开通和管」的顺序说明。
会话、消息、工具结果均按当前登录用户隔离，用户只能看到自己的数据。文末附权限编码一览，供分配角色时对照。
1. 功能一览
| 功能 | 谁在用 | 菜单 / 入口 | 需要的权限 |
|---|---|---|---|
| AI 办公助手 | 业务用户 | 顶栏助手图标，或 AI应用 → AI 办公助手 | ai:chat |
| 我的用量 | 业务用户 | AI应用 → 我的用量 | ai:usage:mine |
| 用量管理 | 管理员 | AI应用 → 用量管理 | ai:usage:list |
| AI 治理 | 平台管理员 | AI应用 → AI治理 | ai:governance:list 等 |
| 页面内 AI 按钮 | 对应模块用户 | 多语言 / 定时任务 / 代码生成 / 登录日志 / 操作日志 | 各模块 *:ai |
| 工作流 AI | 审批相关用户 | 工作流模块内（生成流程、审批建议、风险预判等） | 工作流相关权限 |
- AI 对话助手：全局办公助手，支持多轮会话、工具调用、流式输出，按用户隔离；
- AI 用量统计：按用户 / 场景 / 天的 token 与金额消耗，管理员看全站（或本租户），用户看本人；
- AI 访问治理：配置额度策略、模型价格、检查 Provider 配置、探活。
2. 普通用户：AI 办公助手
权限：登录即可调用，前端入口需分配
ai:chat后才会显示。
2.1 打开助手
- 管理员为角色分配
ai:chat后，顶栏会出现助手入口，菜单 AI应用 → AI 办公助手 也会出现； - 未分配该权限时，菜单里看不到入口；
- 额度用尽时，发送前会提示，需等待恢复或联系管理员调整策略。
2.2 会话管理
| 操作 | 说明 |
|---|---|
| 会话列表 | 当前用户的会话，最近更新倒序，最多 50 条 |
| 新建会话 | 点「新对话」，或直接发第一条消息自动创建 |
| 重命名 | 修改会话标题 |
| 删除会话 | 连同历史消息一起删除，不可恢复 |
| 历史消息 | 按时间升序展示 |
- 发第一条消息时，系统会自动建会话并根据内容生成标题；
- 单条消息建议不超过 2000 字。
2.3 发送消息
- 输入框回车或点发送即可，回复为流式逐字输出；
- 同一会话内可连续追问，助手会带上最近的历史消息（最多 20 条）；
- 若回复为空，会提示换种说法重试。
2.4 怎么提问
助手会按你的问题自动选用工具，不必手动选功能。适合例如：
| 你可以这样说 | 助手可能做什么 |
|---|---|
| 「我今天有什么安排」 | 查本人日程 |
| 「帮我记一下：明天下午 3 点和产品过需求」 | 解析成日程草稿（不直接落库） |
| 「写一下本周周报」 | 根据本人日程生成周报草稿 |
| 「最近 7 天每天登录次数画个折线图」 | 查预注册图表数据并在对话里出图 |
| 「最近登录有没有异常」 | 登录安全分析（需对应日志权限） |
| 「我有哪些待办」 | 查工作流待办 |
打开助手时的空状态会列出你可用的示例问句，点击即填入输入框，照着问最省事。
不会替你点保存、审批、删除。 生成的是草稿或查询结果，真正改数据请到对应模块确认。
没有对应权限的能力不会出现在助手的可选范围里；确实需要时请联系管理员授权，助手只会提示「请联系管理员授权」，不会给出权限编码。
2.5 发图提问
输入框可 点图片按钮上传 或 直接粘贴截图。
- 最多 4 张，单张不超过 4MB，格式：jpg / png / gif / webp / bmp；
- 可只发图、也可图 + 文字，例如：「这张报错截图是什么原因」；
- 本轮有图时只看图回答，不会调用查询工具（不会查日程、出图表）。需要查系统数据时，去掉图片后再发文字；
- 看不清的文字、数字助手不应编造，需要查库请到对应模块或纯文字再问。
管理员需为当前供应商配置视觉模型，未配置时发图会提示无法看图。
2.6 流式回复与停止
- 回复以打字机方式逐字出现；调用工具时会显示「正在调用 / 已调用某某」；
- 生成过程中可点 停止；
- 失败气泡可 重试（会重发同一段文字和图片）。
2.7 查看用量
有 ai:usage:mine 时，可打开 我的用量：看自己的 token、金额、按天/按场景汇总，并可导出流水。看不到其他人的数据（即便管理员从「我的用量」进入也只看自己）。
2.8 对话请求流程图
一次对话从前端发起到结果返回的完整链路如下（普通对话与流式对话共用同一套编排，仅返回形式不同）：
链路要点：
- 鉴权与隔离：接口层仅校验
common（登录即可调用），前端入口另需ai:chat权限方可显示；会话、消息、工具数据均按当前登录用户隔离，越权访问在ResolveSession/ 消息查询处直接拒绝。 - 工具可见性：下发给模型的工具数组与工具清单接口同源——均按用户权限过滤（
monitor:logininfor:ai、monitor:operlog:ai等），保证「前端清单所见即模型可用」。 - 多轮工具调用：模型一轮可能返回多个工具调用，逐个执行并把结果回灌后再次请求模型，最多
MaxToolRounds（5）轮收敛出最终答复；流式场景下每一步以tool start / done事件实时推送。 - 配额与治理：额度、并发、访问策略在模型调用层与
aichat/quota（只读快照）侧提供；治理策略优先级user > role > tenant > global，30 秒缓存自动生效。 - 流式保活：
aichat/chat/stream关闭代理缓冲（X-Accel-Buffering: no）并内置 20s 心跳，避免工具执行 / 模型换轮停顿导致链路被中间代理掐断。 - 用量落账：每轮 token 由模型返回值累计，最终在
FinishTurnAsync随助手消息落库，供「AI 用量统计」核对成本。
3. 各业务页上的 AI 按钮
这些入口挂在原有功能页上，需同时有该页权限和对应 AI 按钮权限。
| 页面 | 按钮权限 | 做什么 |
|---|---|---|
| 系统管理 → 多语言 | system:lang:ai | 批量翻译文案草稿 |
| 监控 → 定时任务 | monitor:job:ai | 自然语言生成 Cron |
| 工具 → 代码生成（编辑表） | tool:gen:ai | 推断列配置 |
| 监控 → 登录日志 | monitor:logininfor:ai | 登录安全分析 |
| 监控 → 操作日志 | monitor:operlog:ai | 操作日志健康分析 |
工作流模块另有：自然语言生成流程、审批意见建议、流程优化、意图匹配填单、实例摘要、风险预判、审批摘要。审批建议与风险预判在有图片附件时可走视觉模型。
4. 管理员：开通与配置
4.1 给角色授权
在角色菜单中勾选：
- 使用助手：
ai:chat - 看自己用量：
ai:usage:mine - 看全站/本租户用量：
ai:usage:list、导出ai:usage:export - 治理与价格、探活：
ai:governance:*、ai:price:*、ai:governance:health - 各业务页 AI 按钮：见第 3 节
用量全站视角仅平台管理员（主租户管理员）可用，其他租户管理员自动只看本租户。
4.2 配置文件
配置在 ZR.Admin.WebApi/ai.json，测试 / 开发环境可用同结构的 ai.Development.json 覆盖。加载优先级从低到高：ai.json → ai.{环境}.json → UserSecrets → 环境变量 → 命令行。
常用字段：
| 字段 | 含义 |
|---|---|
Enable | 总开关 |
Provider | 当前使用的供应商标识，需与 Providers 中某项一致，如 qwen / openai / ollama |
Providers[] | 各家 BaseUrl、ApiKey、文本 Model、看图 VisionModel |
TimeoutSeconds | 全局超时（秒）；分项可单独设更长超时（如本地 Ollama） |
ChatRateLimitPerMinute | 单用户每分钟对话条数，0 不限制 |
DefaultUserTotalTokens | 对话场景月度 token 兜底上限 |
AttachmentDownloadAllowedHosts | 发图/下附件域名白名单；空表示不限制 host |
密钥不要提交到仓库。 生产环境推荐用环境变量注入：
# 当前 Provider 使用的 Key（优先于分项空 Key）
$env:AiOptions__ApiKey = "sk-你的密钥"
# 或指定某一家（下标以实际 json 中 Providers 顺序为准）
$env:AiOptions__Providers__2__ApiKey = "sk-千问密钥"
改环境变量或 json 后需重启 API 生效。
4.3 视觉模型
同一家供应商通常共用 BaseUrl / ApiKey，只换模型名：
"Model": "qwen3.7-plus",
"VisionModel": "qwen3.7-flash"
百炼每个模型免费额度独立。专用 VL（qwen3-vl-*）额度用尽后，可把 VisionModel 设成仍有余量的文本 flash（如 qwen3.7-flash / 带日期快照），它们已支持看图；付费场景再用 qwen3-vl-plus。
看图要换另一家时，用顶层覆盖：VisionProvider、VisionModel、VisionApiKey 等。
未配 VisionModel 时发图会失败；治理页「配置检查」会显示视觉是否已配置。
4.4 本地 Ollama（可选）
ai.json 已预置 ollama 分项，默认 http://127.0.0.1:11434/v1。需要完全离线或做连通性验证时，把顶层 Provider 改为 ollama，并先拉取模型：
ollama pull qwen2.5:7b
ollama pull llava
- 本地一般不需要云厂商 Key，可用占位
ApiKey: "ollama"； - 办公助手每轮会带工具列表，本地小模型响应较慢，正式办公仍建议云端模型；
- 模型名必须与
ollama list一致；Ollama 在其他机器时把BaseUrl指向http://host:11434/v1； - 看图另配
VisionModel（如llava）。
4.5 用量、价格与策略
- 用量管理：按天、场景、用户看 token 与金额；金额 = 调用时「模型价格 × token」；
- 模型价格：在 AI 治理中维护每百万 token 的输入/输出单价；
- 访问策略：按
global / tenant / role / user配置日/月 token、金额、并发。优先级 user > role > tenant > global。场景填具体名或*兜底。变更后最多约 30 秒生效，无需重启； - 配置检查 / 探活：检查开关、地址、Key、视觉配置；探活会真实打一次轻量对话（场景
health_check）。
4.6 策略可用场景
策略与用量统计中的场景取值：
* 默认规则
ai_chat 全局 AI 对话助手
lang_translate 翻译
cron_parse Cron 表达式解析
schedule_parse 日程解析
weekly_report 周报生成
gen_columns 代码生成列推断
login_security 登录安全日志 AI 分析
oper_health 操作日志 AI 健康分析
wf_generate 工作流流程生成
wf_approval_suggest 工作流审批建议
wf_flow_optimize 工作流流程优化
wf_intent_match 工作流意图匹配
wf_instance_summary 工作流实例摘要
wf_risk_check 工作流风险检查
wf_approval_summary 工作流审批汇总
health_check Provider 探活
用具体场景名做精细化额度控制，或用
*作为该作用域的兜底规则。
5. AI 用量统计
管理端：权限
ai:usage:list（导出为ai:usage:export）。数据范围按「平台管理员」收窄——仅平台管理员（主租户管理员）可跨租户查看全站；其他租户管理员仅能看本租户。 个人端：权限ai:usage:mine，强制按当前登录人过滤（即便管理员从「我的用量」进入也只看自己）。
5.1 管理员视角（全站 / 本租户）
| 视图 | 说明 |
|---|---|
| 全站汇总 | 累计 + 按天 + 按场景 |
| 按用户聚合 | 时间段内各用户 token 消耗 |
| 调用流水 | 分页流水，可指定用户 |
| 导出流水 | 按当前筛选导出 Excel（最多 10000 条），需 ai:usage:export |
5.2 个人视角（仅本人）
| 视图 | 说明 |
|---|---|
| 本人汇总 | 累计 + 按天 + 按场景 |
| 本人流水 | 分页流水 |
| 导出本人流水 | 当前筛选导出 Excel（最多 10000 条） |
查询条件为时间范围、场景、用户（管理端）等，时间窗默认 30 天。
5.3 使用提示
- 金额由调用时按「模型价格 × token 用量」实时计算并落账，可在用量页面核对成本；
- 未在 AI 治理中维护价格的模型，金额显示为 0，请先补价格；
- 个人用户只能查看自己的消耗，无法看到他人数据。
6. AI 访问治理
面向平台管理员（超管）或具备
ai:governance:*权限的角色。策略集中存放于主库，支持global / tenant / role / user多级作用域。
6.1 能力概览
进入治理页会先返回当前用户可管理的范围：
| 标识 | 含义 |
|---|---|
isPlatformAdmin | 是否平台超管 |
canManageGlobalPolicy | 能否管理全局策略 |
canManageModelPrice | 能否管理模型价格 |
canCheckProvider | 能否检查 / 探活 Provider |
权限：ai:governance:list。
6.2 模型价格
| 操作 | 权限 |
|---|---|
| 价格列表 | ai:price:list |
| 价格详情 | ai:price:query |
| 新增 | ai:price:add |
| 编辑 | ai:price:edit |
| 删除 | ai:price:remove |
价格字段：
- 供应商 / 模型名：与
ai.json中Provider、Model一致才能匹配到用量； - 输入 / 输出单价：每百万 token 的价格；
- 币种：默认
CNY； - 状态：启用 / 停用。
6.3 访问与额度策略
策略按「作用域 + 场景」定义额度上限，优先级：user > role > tenant > global。命中时按「作用域 + 租户 + 对象」取最具体的一档。
| 操作 | 权限 |
|---|---|
| 策略列表 | ai:governance:list |
| 策略详情 | ai:governance:query |
| 新增 | ai:governance:add |
| 编辑 | ai:governance:edit |
| 删除 | ai:governance:remove |
策略字段：
- 作用域：全局 / 租户 / 角色 / 用户；
- 租户 / 对象：租户标识，以及角色或用户 ID（全局、租户级留空）；
- 场景：能力场景，
*表示该作用域默认规则（可用场景见 4.6）； - 启用状态：空=继承上级；禁用=不参与计算；启用=生效；
- 日 / 月 token 上限：留空表示不限制；
- 日 / 月金额上限（元）；
- 并发上限：同时进行的 AI 调用数。
策略变更后约 30 秒内自动生效，无需重启服务。
6.4 Provider 配置检查与探活
| 操作 | 说明 | 权限 |
|---|---|---|
| 配置检查 | 校验启用状态、Provider、BaseUrl、ApiKey、视觉能力等，返回告警列表（只读，不影响线上） | ai:governance:health |
| Provider 探活 | 实测一次对话连通性，返回延迟、HTTP 状态码、Provider 请求 ID | ai:governance:health |
探活会真实发起一次轻量调用（场景 health_check），用于确认 Provider 当前可用。
7. 助手能力边界
会做
- 多轮对话、流式输出、停止生成；
- 查本人日程 / 解析日程草稿 / 生成周报草稿；
- 有权限时：登录安全、操作日志健康、预注册趋势图、工作流待办；
- 发图理解截图、表格、单据（不调查询工具）。
不会做
- 自由编写 SQL、直接改库；
- 代替你在模块里保存、审批、删除；
- 知识库 / RAG 检索（当前没有）；
- 文生图、改图；
- 把别人的会话或用量给你看；
- 业务用户在对话里自选模型（由管理员在配置中指定）。
图表只走预注册数据集（如登录次数、操作日志统计），未注册的业务指标请到对应模块查看。
8. 权限编码一览
| 权限编码 | 说明 |
|---|---|
common | 任意登录用户可调用对话接口（前端入口仍需 ai:chat） |
ai:chat | AI 办公助手入口权限（分配后前端才显示助手入口） |
ai:usage:mine | 个人用量查询（我的用量） |
ai:usage:list | 管理端全站 / 本租户用量 |
ai:usage:export | 管理端用量导出 |
ai:governance:list | 治理列表 / 能力概览 |
ai:governance:query | 策略详情 |
ai:governance:add / edit / remove | 策略增改删 |
ai:price:list / query / add / edit / remove | 模型价格管理 |
ai:governance:health | Provider 配置检查 / 探活 |
system:lang:ai | 多语言 AI 翻译 |
monitor:job:ai | Cron AI 生成 |
tool:gen:ai | 代码生成列推断 |
monitor:logininfor:ai | 登录日志 AI 分析 |
monitor:operlog:ai | 操作日志 AI 分析 |
角色未分配对应权限时，菜单与按钮都不会显示。跨租户全站视角仅对平台管理员（主租户管理员）开放，其他租户管理员自动收窄到本租户。
9. 常见问题
Q：看不到助手入口？ 角色未分配 ai:chat，或未重新登录刷新菜单。
Q：提示额度不足？ 日/月 token 或金额触达策略上限。看「我的用量」或请管理员调整策略。
Q：发图提示未配置视觉模型 / HTTP 403？ 当前 Provider 未填 VisionModel，或顶层覆盖把视觉模型清空了。百炼每个模型免费额度独立，额度用尽或开了「仅用免费额度」会 403；可换成仍有余量的模型（如 qwen3.7-flash），或充值后用 qwen3-vl-plus。
Q：发图后不查日程 / 不出图？ 有图本轮只看图。去掉图片再用文字问。
Q：对话特别慢（一两分钟）？ 本地 Ollama 小模型带工具列表时响应明显偏慢。正式环境请用云端多模态/对话模型。
Q：策略改了没立刻生效？ 最多约 30 秒生效，无需重启。
Q：查不到全站用量？ 需要 ai:usage:list 且为平台管理员（主租户管理员）；其他租户管理员仅能看本租户，普通管理员请使用个人视角或申请对应权限。
Q：Provider 探活失败代表什么？ 仅表示探活时刻该 Provider 不可达（网络、Key、额度或模型名问题）。可用治理页「配置检查」看具体告警项。
Q：密钥写在 json 里安全吗？ 生产环境不要把真实 Key 提交到 git，用环境变量注入。
Q：如何用本地 Ollama？ai.json 已预置 ollama 分项。把顶层 Provider 改为 ollama，BaseUrl 指向本机或局域网 http://host:11434/v1，模型名与 ollama list 一致；看图另配 VisionModel（如 llava）。本地可用占位 Key，不必填云厂商密钥。
Q：普通用户能看到的 AI 数据范围？ 对话助手只看自己的会话；用量统计（ai:usage:mine）只看本人的消耗汇总与流水。