bigquery-agent-analytics-sdk

用途

BigQuery Agent Analytics SDK 是一个开源 Python 工具包，用于分析存储在 BigQuery 中的 AI 智能体遥测数据。它面向在生产环境中运行智能体的 ML 工程师，帮助他们衡量质量、理解行为并大规模检测回归。

主要能力

可观测性：轨迹重建、DAG 可视化、按事件类型创建 BigQuery 视图。
评估：LLM-as-Judge 评估、轨迹匹配、多轮 pass@k 评估、评分器组合（加权平均、二值阈值、多数投票）、评估套件生命周期管理。
高级分析：Agent Context Graph 用于决策轨迹提取、漂移检测、记忆服务。
AI/ML 集成：BigQuery AI 函数，如 AI.GENERATE 生成摘要、AI.CLASSIFY 分类情感。

使用方式

安装

# 核心 SDK
pip install bigquery-agent-analytics

# 带 LLM judge 支持
pip install bigquery-agent-analytics[llm]

# 带 BigFrames 支持
pip install bigquery-agent-analytics[bigframes]

# 所有功能
pip install bigquery-agent-analytics[llm,bigframes]

前置条件：

Python 3.10+
已启用 BigQuery 的 Google Cloud 项目
BigQuery 中的智能体轨迹（通过 ADK BigQuery Trace Exporter）
已配置 GOOGLE_APPLICATION_CREDENTIALS 或 gcloud auth application-default login

核心客户端 API

from bigquery_agent_analytics import Client

client = Client(
    project_id="my-gcp-project",
    dataset_id="agent_analytics"
)

CLI 命令

SDK 包含 bqaa（或 bq-agent-sdk）CLI，提供 12+ 命令，涵盖诊断、视图管理、评估、Agent Context Graph 等。

评估示例

from bigquery_agent_analytics.evaluators import LLMAsJudge

judge = LLMAsJudge(
    client=client,
    model_name="gemini-2.0-flash-exp",
    criteria=["correctness", "hallucination", "helpfulness"]
)

llm_results = judge.evaluate_traces(
    trace_ids=["trace-1", "trace-2", "trace-3"]
)

Agent Context Graph

从智能体上下文中提取决策轨迹：处理了哪些请求、权衡了哪些选项、提交了哪些结果，并物化为 BigQuery 属性图。

bqaa context-graph --project-id $PROJECT_ID --dataset-id agent_analytics \
    --graph agent_decisions_graph --lookback-hours 24 --format json

适用场景

生产环境中运行 AI 智能体的 ML 工程师
需要大规模衡量智能体质量、理解行为并检测回归的团队
使用 BigQuery 存储智能体遥测数据的组织

限制

需要 Python 3.10+
需要已启用 BigQuery 的 Google Cloud 项目
需要 BigQuery 中已有智能体轨迹数据
需要配置 Google Cloud 认证
部分功能（如 LLM judge、BigFrames）需要额外安装可选依赖
关于收费、价格、平台支持范围等具体信息暂未提供