UIP 追踪反馈

“uip Traces反馈”的语法和选项，用于创建并管理附加到追踪或跨度的 LLM 可观察性反馈。

uip traces feedback 管理 LLM 可观察性反馈，即附加到追踪或跨度的正面/负面评分、注释和类别标签。使用它来记录对智能体输出的人工审核，或拉取记录的反馈以进行报告。

此页面是uip traces工具的一部分 — 请参阅该页面以了解spans get 。

大纲

uip traces feedback create --trace-id <id> (--positive | --negative) --folder-key <guid> [--span-id <id>] [--comment <text> | --comment-file <path>] [--category <tag>...] [--agent-id <guid>] [--agent-version <str>]
uip traces feedback get <id> [--folder-key <guid>]
uip traces feedback list [--agent-id <guid>] [--agent-version <str>] [--trace-id <id>] [--span-id <id>] [--status <value>...] [--positive | --negative] [--limit <n>] [--offset <n>] [--folder-key <guid>]
uip traces feedback list detailed [--agent-id <guid>] [--agent-version <str>] [--trace-id <id>] [--span-id <id>] [--status <value>...] [--positive | --negative] [--category-id <guid>...] [--after <iso> | --since <duration>] [--before <iso>] [--sort-by <field>] [--sort-order <dir>] [--limit <n>] [--offset <n>] [--folder-key <guid>]
uip traces feedback update <id> (--positive | --negative) --folder-key <guid> [--comment <text> | --comment-file <path>] [--metadata <json> | --metadata-file <path>] [--category <tag>...]
uip traces feedback delete <id> --folder-key <guid> -y

所有动词都遵循全局选项和标准退出代码。

UIP 追踪反馈创建

为追踪（或其中的特定跨度）创建反馈。

选项

标记	描述
--trace-id <id>	必需。追踪 ID（32 个字符的十六进制或 GUID）。
--positive / --negative	必填 — 正好一个。反馈的情感。
--folder-key <guid>	必需。Orchestrator 文件夹密钥。
--span-id <id>	跨度 ID。省略时，默认为追踪的根跨度。
--comment <text>	自由文本批注（最多 1,048,576 个字符）。与 --comment-file 互斥。
--comment-file <path>	读取文件中的注释；传递 - 以从标准输入读取。与 --comment 互斥。
--category <tag>	类别标签。可重复。该平台可识别 Output、Agent Error 和 Agent Plan Execution 等内置标签，但也接受任何字符串。
--agent-id <guid>	智能体引用 ID。
--agent-version <str>	智能体版本（最多 100 个字符）。

示例

uip traces feedback create \
  --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 \
  --positive \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "FeedbackCreate",
  "Data": { "Id": "a1b2c3d4-0000-0000-0000-000000000002" }
}

Data 是反馈 API 返回的任何内容的未经修改的传递 — CLI 不会将其映射到固定字段集，因此实际响应可能包含比此处显示的更多的字段。

获取 UIP 追踪反馈

按 ID 获取单个反馈记录。

参数

• <id> （必填） — 反馈记录 ID (GUID)。客户端由于“反馈 ID 格式无效”而发生故障如果它不是 GUID

选项

标记	描述
--folder-key <guid>	Orchestrator 文件夹密钥。服务器通常需要它来授权读取，即使没有它的客户端 CLI 不会发生硬故障。

示例

uip traces feedback get a1b2c3d4-0000-0000-0000-000000000002 \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "FeedbackGet",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000002",
    "IsPositive": true
  }
}

与 create 一样，Data 是原始传递 — 真实响应包含的字段（注释、元数据、类别、时间戳）通常比这个最小示例显示的要多。

UIP 跟踪反馈列表

列出反馈条目，按追踪记录、跨度、智能体、状态或情感筛选。

选项

标记	描述
--agent-id <guid>	按智能体 ID 筛选。
--agent-version <str>	按智能体版本筛选。
--trace-id <id>	按追踪 ID 筛选。
--span-id <id>	按跨度 ID 筛选。
--status <value>	按状态筛选：Pending、Approved、Dismissed。可重复。
--positive / --negative	仅返回正面反馈或负面反馈。互斥。
--limit <n>	最大结果数量。默认为 20，上限为 100。
--offset <n>	要跳过的结果。默认为 0。
--folder-key <guid>	Orchestrator 文件夹密钥。

示例

uip traces feedback list --trace-id 4bf92f3577b34da6a3ce929d0e0e4736

数据形状

{
  "Code": "FeedbackList",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000002",
      "IsPositive": true
    }
  ]
}

空结果将打印“未找到反馈。使用“uip Traces反馈创建”以添加反馈。

UIP 追踪反馈列表详情

列出具有扩展筛选器（时间窗口、类别、排序）和跨度上下文的反馈。这是list子命令，而不是顶级动词 — 调用是带有空格的uip traces feedback list detailed ，而不是list-detailed 。

选项

标记	描述
--agent-id <guid>	按智能体 ID 筛选。
--agent-version <str>	按智能体版本筛选。
--trace-id <id>	按追踪 ID 筛选。
--span-id <id>	按跨度 ID 筛选。
--status <value>	按状态筛选：Pending、Approved、Dismissed。可重复。
--positive / --negative	仅返回正面反馈或负面反馈。互斥。
--category-id <guid>	按类别 ID 筛选。可重复。
--after <iso>	在此 ISO 8601 时间戳之后创建。
--before <iso>	创建在此 ISO 8601 时间戳之前。
--since <duration>	--after 的相对回顾简写 — 例如 1h、24h、7d。仅接受 h（小时）和 d（天）单位。
--sort-by <field>	对字段进行排序：createdAt 或 updatedAt。默认为 createdAt。
--sort-order <dir>	排序方向：asc 或 desc。默认为 desc。
--limit <n>	最大结果数量。默认为 20，上限为 200（高于普通 list 的上限 100）。
--offset <n>	要跳过的结果。默认为 0。
--folder-key <guid>	Orchestrator 文件夹密钥。

备注：

--since 和 --after 都设置了相同的基础开始时间筛选条件 — --since 的评估相对于流程中的“现在”进行在命令运行时刻。

示例

uip traces feedback list detailed --since 24h

数据形状

{
  "Code": "FeedbackListDetailed",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000002",
      "IsPositive": true,
      "TraceId": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  ]
}

基础 API 响应已分页 ({ items, totalCount })，但 CLI 仅将 items 数组发出为 Data — 不显示匹配项总数 (totalCount)。要了解是否存在除 --limit 以外的更多结果，请将返回的计数与 --limit 进行比较，而不是依赖总数。

UIP 追踪反馈更新

更新现有反馈记录的情感、评论、元数据或类别。

重要提示：

API 会替换整个记录，而不是修补它，因此 CLI 首先读取现有记录，并结转您未传递的任何字段 — --category 除外：省略它不会影响现有类别，但这种“先读取后写入”方式非必需。读取和写入之间的并发编辑登陆将丢失（静默）。

参数

• <id> （必填） — 反馈记录 ID (GUID)。

选项

标记	描述
--positive / --negative	必填 — 正好一个。新情感。
--folder-key <guid>	必需。Orchestrator 文件夹密钥。
--comment <text>	已更新注释（最多 1,048,576 个字符）。与 --comment-file 互斥。省略以保留现有注释。
--comment-file <path>	读取文件中更新的注释；对于标准输入，传递 -。与 --comment 互斥。
--metadata <json>	更新了元数据；必须为有效的 JSON（最多 1,048,576 个字符）。与 --metadata-file 互斥。省略以保留现有元数据。
--metadata-file <path>	从文件中读取更新的元数据；对于标准输入，传递 -。与 --metadata 互斥。
--category <tag>	替换类别标签。可重复。完全省略以将现有类别保持原样 — 传递的类别会替换完整的类别，也不会合并。

示例

# change sentiment and add a comment
uip traces feedback update a1b2c3d4-0000-0000-0000-000000000002 \
  --negative \
  --comment "Wrong output" \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

# attach metadata read from a file
uip traces feedback update a1b2c3d4-0000-0000-0000-000000000002 \
  --positive \
  --metadata-file review.json \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "FeedbackUpdate",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000002",
    "IsPositive": false
  }
}

UIP 追踪反馈删除

按 ID 删除反馈记录。这是破坏性操作 — 需要-y, --yes ； CLI 从不提示。

参数

• <id> （必填） — 反馈记录 ID (GUID)。

选项

标记	描述
--folder-key <guid>	必需。Orchestrator 文件夹密钥。
-y, --yes	确认此不可逆操作。必需 — CLI 从不提示。

示例

uip traces feedback delete a1b2c3d4-0000-0000-0000-000000000002 \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001 \
  --yes

数据形状

{
  "Code": "FeedbackDelete",
  "Data": { "Id": "a1b2c3d4-0000-0000-0000-000000000002" }
}

错误行为

• 来自反馈 API 的 401：Failure: "Not authenticated. Run 'uip auth login' first."。
• 403：Failure: "Insufficient permissions. Ensure you have Logs.View / Logs.Create / Logs.Delete on this folder."。
• 404：Failure 命名缺少的反馈 ID。
• 非 GUID 的 ID（get、update、delete）：Failure: "Invalid feedback ID format: <id>"，已在任何网络调用之前在客户端进行检查。

相关内容

• uip traces spans get — 上面使用的--trace-id / --span-id值的来源。
• 工具（插件） — 安装、更新、卸载traces-tool包。
• uip login — 用于对此页面上的每个谓词进行身份验证的会话。

另请参阅

• uip traces