NocoBase 的近期更新加入了结构化 AI 使用记录。对正在把大模型能力接入业务流程的团队来说，这类记录不只是“多了一张日志表”：它让一次 AI 调用可以被查询、统计和审计，也为成本核算、故障排查与提示词迭代提供数据基础。
本轮更新仍沿用 main、next 和 develop 三个分支。团队在尝试 AI 相关新功能时，需要先选对分支，再决定记录哪些字段、如何控制敏感数据，以及怎样把日志转化为可操作的指标。
为什么 AI 调用需要结构化记录
普通文本日志适合临时排错，却很难回答运营问题。例如，团队可能需要知道：
- 哪个工作流调用 AI 最频繁；
- 某个模型的失败率是否突然升高；
- 输入、输出分别消耗了多少 token；
- 用户最终是否采纳了生成结果；
- 哪个提示词版本带来了更稳定的结果。
结构化记录的关键，是把一次调用拆成稳定字段，而不是把所有信息塞进一段文本。一个可用于实践的最小模型通常包括：
| 字段 | 用途 |
|---|---|
request_id |
串联业务请求、AI 调用与错误日志 |
workflow |
标识调用来自哪个业务流程 |
model |
记录实际使用的模型 |
prompt_version |
比较不同提示词版本 |
input_tokens / output_tokens |
分析用量与成本 |
latency_ms |
定位响应变慢的问题 |
status |
区分成功、失败和超时 |
created_at |
支持时间范围统计 |
来源摘要没有给出 NocoBase 该功能的具体字段和接口，因此上表应视为建模建议，而不是产品内置字段清单。落地时应以当前版本中的实际数据表和插件配置为准。
三个分支该怎么选
NocoBase 当前维护三个更新分支，它们对应不同的稳定性预期：
main：目前最稳定，推荐用于正式安装和生产环境。next：包含即将发布并经过初步测试的功能，仍可能存在已知或未知问题，适合测试用户提前体验并反馈。develop：面向持续开发。摘要没有提供其稳定性承诺，不应默认适合承载生产数据。
如果目标是验证结构化 AI 使用记录，可以在隔离环境尝试 next；如果生产系统更看重稳定性，则应继续使用 main，等待目标能力进入稳定版本。无论选择哪个分支，都不要直接拿生产数据库做首次升级测试。
可以用下面的检查清单约束升级流程：
# 进入现有部署目录后，先确认当前分支和工作区状态
git branch --show-current
git status --short
# 获取远端更新，但暂不修改当前工作区
git fetch --all --prune
# 查看三个远端分支最近一次提交
git log -1 --oneline origin/main
git log -1 --oneline origin/next
git log -1 --oneline origin/develop
执行前需要把仓库远端名称确认成实际使用的 origin。升级之前还应备份数据库、附件和环境配置，并在测试实例中执行同样的迁移流程。
可以这样实践：先定义一条可查询的 AI 记录
在尚未确认 NocoBase 当前版本具体 API 的情况下，可以先用一个本地脚本验证数据模型。下面的 Python 示例不依赖第三方包，会创建 SQLite 数据库、写入一条模拟 AI 调用记录，并按工作流汇总调用次数、token 数和平均延迟。
将代码保存为 ai_usage_demo.py，然后运行 python ai_usage_demo.py：
import sqlite3
import uuid
from datetime import datetime, timezone
DB_PATH = "ai_usage.db"
with sqlite3.connect(DB_PATH) as conn:
conn.execute("""
CREATE TABLE IF NOT EXISTS ai_usage (
request_id TEXT PRIMARY KEY,
workflow TEXT NOT NULL,
model TEXT NOT NULL,
prompt_version TEXT NOT NULL,
input_tokens INTEGER NOT NULL,
output_tokens INTEGER NOT NULL,
latency_ms INTEGER NOT NULL,
status TEXT NOT NULL,
created_at TEXT NOT NULL
)
""")
conn.execute(
"""
INSERT INTO ai_usage VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
str(uuid.uuid4()),
"customer-summary",
"example-model",
"v3",
820,
214,
1460,
"success",
datetime.now(timezone.utc).isoformat(),
),
)
rows = conn.execute("""
SELECT
workflow,
COUNT(*) AS calls,
SUM(input_tokens + output_tokens) AS total_tokens,
ROUND(AVG(latency_ms), 1) AS avg_latency_ms
FROM ai_usage
GROUP BY workflow
ORDER BY calls DESC
""").fetchall()
for workflow, calls, total_tokens, avg_latency_ms in rows:
print({
"workflow": workflow,
"calls": calls,
"total_tokens": total_tokens,
"avg_latency_ms": avg_latency_ms,
})
预期输出类似：
{'workflow': 'customer-summary', 'calls': 1, 'total_tokens': 1034, 'avg_latency_ms': 1460.0}
验证字段能够回答实际问题后，可以在 NocoBase 中建立对应的数据表和视图，再通过当前版本支持的工作流节点、插件或 API 写入记录。接口路径、鉴权方式和字段映射必须根据实际安装版本调整，不应直接假设存在某个固定端点。
记录越完整，数据治理压力越大
AI 使用记录可能包含客户资料、内部文档片段、提示词和模型输出。为了排查问题而保存完整输入输出，很容易扩大敏感数据的暴露范围。
建议至少设置以下边界：
- 默认记录模型、token、耗时、状态和业务标识，不默认保存完整提示词与输出；
- 对邮箱、手机号、证件号和访问令牌进行脱敏；
- 为日志表配置独立权限，限制批量导出；
- 明确保留周期，到期删除或聚合原始记录；
- 记录
prompt_version，但不要把密钥写入提示词或日志； - 对失败率、超时率和用量突增建立告警。
上线前的取舍
结构化 AI 使用记录最适合从“小而稳定”的字段集合开始。先确保每条记录都能关联到业务流程和请求 ID，再补充成本、质量反馈等字段。过早保存全部上下文，会增加存储、权限和合规负担；字段过少，又无法解释模型为何变慢或成本为何上涨。
生产环境优先采用 main。需要验证新能力时，在独立数据库和隔离实例中评估 next，确认迁移、权限、脱敏和回滚流程后再扩大范围。真正有价值的 AI 日志，不是记录得最多，而是能够持续回答成本、稳定性和业务效果三个问题。