jwuthri-cloud/Tracely-ai

Tracely – AI 代理可观测性与回归测试

它是什么 – Tracely 是一个自托管平台，监控您的 AI 代理（LLM 驱动的机器人、使用工具的助手、多代理系统）在生产环境中的运行，将看到的任何失败转化为确定性回归测试，并阻止重新引入相同 bug 的拉取请求。它通过摄取 OpenTelemetry 风格的追踪、使用内置评估器评估、聚类相似失败，并在 CI 中重放精确记录的输入/输出来实现。

关键组件

• 摄取服务 – 从任何语言接收 OTLP/HTTP 追踪，将原始 span 存储在 ClickHouse/Postgres 中，并索引代理特定字段（代理 ID、对话 ID、轮次、步骤）。
• 评估器/评判器 – 轻量级检查（无模型）加上基于 LLM 的评判器，对运行、轮次或 span 进行评分。判定结果作为列写回追踪表。
• 失败聚类 – 按结构签名和语义嵌入对失败运行进行分组，生成一个带有计数和建议评估器的单一 问题。
• 回归用例 – 一键将失败追踪提升为封闭测试用例：所有输入、工具调用和 LLM 输出保存为夹具，附加“失败到通过”契约，并定义可选断言。
• CI 门禁 – 一个 CLI（tracely gate/tracely simulate/tracely replay）在 GitHub Actions 中运行测试套件，失败时以非零退出，发布提交状态和 PR 评论。
• 警报流程 – 可视化构建器，用于“当-则”规则（例如，门禁失败、出现新失败类型、超过速率阈值）。操作可以是 Slack、电子邮件、webhook、LLM 步骤或 Python 表达式。
• 仪表板与视图 – 追踪时间线、分层瀑布图、“Fleet”像素艺术办公室视图、随时间趋势、评判器校准屏幕，以及一个应用内助手，可以通过自然语言创建评估器、场景、用例和警报。

如何使用

1. 插桩 您的代理使用 tracelyai-sdk（或任何 OTLP 导出器）。SDK 自动捕获 OpenAI/Anthropic/Google/Mistral 调用、工具使用、token 使用、延迟等。
2. 运行 您的服务在生产环境；Tracely 将每个对话存储为追踪。
3. 检测 – 评估器实时对运行进行评分；失败自动聚类。
4. 提升 一键将失败提升为回归用例。
5. 部署 – 将 Tracely GitHub Action 添加到您的 PR 工作流；门禁离线重放用例夹具（无需 API 密钥，$0 成本），如果 bug 返回则阻止 PR。
6. 监控 – 仪表板显示失败计数、门禁通过率、延迟/成本趋势，并允许您根据人工审查校准评判器。

安装与部署

• 通过提供的按钮一键部署到 Railway 或 Railyard。
• 完整的 Docker-Compose 技术栈（backend、worker、frontend、ClickHouse、Postgres、Redis、MinIO）– docker compose --profile demo up 启动一个带有预填充追踪、聚类、用例和门禁的演示。
• 对于自定义基础设施，请参阅 deploy/railway 和 deploy/eks 指南；该技术栈在单个 Kubernetes 命名空间中运行。

典型工作流代码片段

import tracely_sdk as tracely
tracely.init(
    endpoint="http://localhost:8000",
    api_key="tracely_dev_key",
    service_name="support-agent",
    env="prod",
    instrument="auto",
)

with tracely.trace(agent="support-agent", conversation="conv-1"):
    client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Where is order ORD-4471?"}],
    )

SDK 记录一个 GENERATION span，包含所有元数据；Tracely 随后对其进行评估，聚类任何失败，并可将其转化为回归用例。

为什么重要 传统的 LLM 评估依赖于手工制作的测试集，这些测试集永远无法完全匹配生产输入。Tracely 颠覆了这种模式：真实的失败运行成为测试，保证完美保真、CI 中零模型调用成本，并自动阻止回归。它弥合了 AI 代理的可观测性和持续集成之间的鸿沟。

链接

• 网站：https://tracely-ai.com
• 文档：https://doc.tracely-ai.com
• PyPI 上的 SDK：tracelyai-sdk
• GitHub Actions：.github/actions/tracely-gate