技能简介

Traccia 是一款面向生产环境的 Python SDK，专注于 AI Agent 和 LLM 应用的运行时可观测性、策略控制与合规审计。它由 OpenTelemetry 驱动，框架无关，支持 OpenAI Agents、LangGraph、CrewAI 等主流框架，能够在不修改业务代码的前提下，自动追踪 Token 消耗、成本、延迟、Prompt 内容、模型响应等关键运行时指标，并在检测到异常策略违规时实时阻断或修正调用行为。

换句话说：Traccia 让 AI Agent 从"黑盒运行"变成"全程透明可控"，是企业级 AI 运维不可或缺的基础设施层。

核心能力

• 运行时策略引擎（@govern）：通过 Spend Cap（支出上限）、Model Boundary（模型边界）、Loop Cap（循环上限）等策略，在调用发起前拦截或改写 LLM 或 Tool 请求
• AI 安全护栏检测：被动感知 AI 安全控制层、平台原生防护措施及自定义护栏的生效状态
• 无侵入式自动插桩：初始化时自动 Patch OpenAI、Anthropic、Gemini（google-genai）等主流 SDK，无需手动埋点
• LLM 可感知追踪：自动记录模型版本、Token 用量（输入/输出分开）、API 成本、单次调用延迟，精度达毫秒级
• 分布式追踪与多后端导出：兼容 OpenTelemetry 协议，可将数据导出至 Grafana Tempo、Jaeger、Zipkin、SigNoz 等主流可观测性平台
• 离线评估（evaluate）：在本地数据集上运行任务与评分器，实验结果自动持久化至平台端，支持对比与版本追溯
• Prompt 管理：通过 load_prompt / prefetch_prompts 实现企业级 Prompt 模板的版本化管理和运行时热加载
• 合规与脱敏：内置 EU AI Act 和 HIPAA 导向的证据链生成、PII/PHI 数据脱敏工具
• 装饰器追踪（@observe）：任意 Python 函数加装饰器即可获得完整调用追踪，适用于 Tool 函数和自定义逻辑

安装配置

环境要求

• Python 3.9 及以上版本
• 推荐使用虚拟环境（venv 或 conda）隔离依赖

安装命令

pip install traccia

如需 LangChain 集成支持，安装可选依赖：

pip install traccia[langchain]

初始化配置

Traccia 支持三种配置方式：

方式一：代码内初始化（推荐用于快速验证）

from traccia import init init() # 自动从环境变量或 traccia.toml 加载配置

方式二：配置文件（适用于团队共享）

在项目根目录创建 traccia.toml：

[api] key = "your-traccia-workspace-api-key" endpoint = "https://api.traccia.ai"

[export] exporter = "console" # 可选: otlp, jaeger, zipkin, signoz, console, file

[tracing] service_name = "my-ai-service" sample_rate = 1.0

方式三：环境变量（适用于容器化部署）

export TRACCIA_API_KEY="your-workspace-api-key" export TRACCIA_ENDPOINT="https://api.traccia.ai" export TRACCIA_EXPORTER="otlp"

使用步骤

步骤一：基础初始化

from traccia import init init() # 完成 SDK 初始化，自动 Patch 主流 LLM SDK

步骤二：为任意函数添加追踪

from traccia import observe

@observe() def my_function(x, y): return x + y

result = my_function(2, 3) # 自动记录调用参数、耗时、返回值

步骤三：追踪 LLM 调用（以 OpenAI 为例）

from traccia import init, observe from openai import OpenAI

init() # 自动 Patch OpenAI SDK client = OpenAI()

@observe(as_type="llm") def generate_text(prompt: str) -> str: response = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": prompt}] ) return response.choices[0].message.content

text = generate_text("用一句话解释量子计算")

自动记录：模型、Token 用量、API 成本、延迟

步骤四：运行时策略控制（@govern）

from traccia import init, govern

init()

定义策略：每次调用成本上限 0.05 美元，模型必须是 GPT-4 或 Claude

@govern(policies=["spend_cap:0.05", "model_boundary:gpt-4,claude-3"]) def ai_task(prompt):

如果超出策略，调用在发出前被阻断或重定向

return call_model(prompt)

步骤五：离线评估与实验对比

from traccia import init, evaluate

init(api_key="...")

prompt = load_prompt("support-reply", label="production")

def task(inp): messages = prompt.compile(**inp) return call_model(messages)

result = evaluate( "support-reply-v3", data="support-golden", task=task, scorers=["exact_match", "contains"], ) print(result.summary()) print(result.url) # 在平台上查看详细实验报告

适用场景

• 场景一：AI 应用生产监控 团队在生产环境部署了多个 LLM Agent，需要统一观测 Token 消耗、调用延迟和错误率，Traccia 的 OTEL 导出可直接对接已有的 Grafana 仪表盘，无需额外开发。

• 场景二：多模型供应商成本管控 企业同时使用 OpenAI、Anthropic 和 Gemini，在切换或路由模型时，Traccia 自动记录每个供应商的调用量和成本，帮助财务团队做 AI 支出分析。

• 场景三：AI 安全合规审计 金融、医疗等强监管行业需要留存 AI 决策依据链。Traccia 的 EU AI Act / HIPAA 合规模块可自动生成带时间戳的操作证据记录，满足监管审查要求。

• 场景四：Prompt 版本管理与 A/B 测试 通过 load_prompt 实现 Prompt 模板的版本化管理，配合 evaluate() 在同一数据集上对比不同 Prompt 版本的效果，加速迭代。

• 场景五：LangGraph / CrewAI 工作流的深度追踪 复杂多步骤 Agent 工作流中，Traccia 自动将每个 Tool 调用和 LLM 决策串联为完整调用链，方便定位某一步的 Token 异常或逻辑错误。

适用人群

• AI 应用开发团队：需要为已有 LLM 应用快速增加可观测性，而不想引入重型的供应商绑定方案
• DevOps / MLOps 工程师：负责 AI 服务的成本核算、容量规划和 SLA 监控
• 安全与合规团队：需要审计 AI 系统的 Prompt 和响应内容，确保符合内部安全策略
• AI 产品经理：关注 AI 功能上线后的真实使用情况，包括用户触达的模型版本、Token 消耗趋势

工作原理

Traccia 的核心架构分为三层：

接入层（Instrumentation）：通过猴子补丁（Monkey Patch）自动拦截主流 LLM SDK 的网络请求，在请求发出前和响应返回后插入追踪逻辑。此方式无需业务代码做任何改动，初始化时一次性完成所有 SDK 的 Patch。

策略层（Governance）：基于 OpenTelemetry 的 Span 上下文，在每个 LLM 或 Tool 调用发起前，根据配置的策略（如 Spend Cap）动态计算预估成本，若超出阈值则通过抛出异常或返回降级响应来阻断调用，而非让请求真正发出。

导出层（Export）：所有追踪数据（Span、Metrics、Logs）均以 OpenTelemetry 协议标准化，通过 OTLP 协议推送到任意兼容后端。同时，本地也支持 Console、File 等轻量级导出方式，方便本地调试。

官方链接

• PyPI 主页：https://pypi.org/project/traccia/
• GitHub 仓库：https://github.com/traccia-ai/traccia-py
• 官方文档：https://traccia.ai/docs
• 在线平台（实验对比与 Prompt 管理）：https://app.traccia.ai