Snowflake 是云数据仓库平台，支持大规模 SQL 分析。通过 OpenRouter Broadcast，每次 LLM 请求的 trace 可直接写入 Snowflake 的 OPENROUTER_TRACES 表，实现自定义分析、长期存储和 BI 报表。配置前需先在 Snowflake 中建表（SQL 在 OpenRouter 配置页面提供），并生成具有 ACCOUNTADMIN 权限的 Programmatic Access Token。表结构设计兼顾查询效率：常用字段（模型、token、费用、用户 ID）为有类型列，自定义元数据和可变结构数据（输入/输出消息）存入 VARIANT 列，可用 Snowflake 半结构化数据语法查询。

Snowflake 是云数据仓库平台，适合大规模 SQL 分析。通过 OpenRouter Broadcast，LLM trace 可直接写入 Snowflake 数据库，与你的业务数据统一存储和分析。

配置步骤

第一步：创建 traces 表

在 Snowflake 中创建 OPENROUTER_TRACES 表。精确的建表 SQL 可在 OpenRouter 配置页面找到（配置 Snowflake 目的地时会显示）。

第二步：创建访问凭证

在 Snowflake 界面的 Settings > Authentication 中，生成具有 ACCOUNTADMIN 权限的 Programmatic Access Token。

第三步：在 OpenRouter 开启 Broadcast

前往 Settings > Observability，打开 Enable Broadcast 开关。

第四步：配置 Snowflake

点击 Snowflake 旁边的编辑图标，填写：

字段	填写内容
Account	Snowflake 账号标识符（如 eac52885.us-east-1，由区域和账号 ID 组合，可在实例 URL 中找到）
Token	Programmatic Access Token
Database	目标数据库（默认 SNOWFLAKE_LEARNING_DB）
Schema	目标 Schema（默认 PUBLIC）
Table	表名（默认 OPENROUTER_TRACES）
Warehouse	计算仓库名（默认 COMPUTE_WH）

第五步：测试并保存

点击 Test Connection 验证配置，测试通过后自动保存。

第六步：验证数据写入

通过 OpenRouter 发送 API 请求，查询 Snowflake 表验证 trace 是否写入。

表结构设计

有类型列（Typed Columns）

常用字段以有类型列存储，支持高效过滤和聚合：

• 标识符：TRACE_ID、USER_ID、SESSION_ID、API_KEY_NAME
• 时间戳：用于时序分析
• 模型信息：MODEL、PROVIDER_NAME
• 指标：TOTAL_TOKENS、TOTAL_COST、PROMPT_TOKENS、COMPLETION_TOKENS、DURATION_MS

VARIANT 列

不常访问或结构可变的数据存入 VARIANT 列：

• ATTRIBUTES：完整 OTEL 属性集
• INPUT/OUTPUT：可变结构的消息内容
• METADATA：用户自定义元数据键值对
• MODEL_PARAMETERS：模型特定参数

SQL 查询示例

按模型分析费用（近 30 天）

SELECT
  DATE_TRUNC('day', TIMESTAMP) as day,
  MODEL,
  SUM(TOTAL_COST) as total_cost,
  SUM(TOTAL_TOKENS) as total_tokens,
  COUNT(*) as request_count
FROM OPENROUTER_TRACES
WHERE TIMESTAMP >= DATEADD(day, -30, CURRENT_TIMESTAMP())
  AND STATUS = 'ok'
  AND SPAN_TYPE = 'GENERATION'
GROUP BY day, MODEL
ORDER BY day DESC, total_cost DESC;

用户活跃度分析

SELECT
  USER_ID,
  COUNT(DISTINCT TRACE_ID) as trace_count,
  SUM(TOTAL_COST) as total_cost,
  AVG(DURATION_MS) as avg_duration_ms
FROM OPENROUTER_TRACES
WHERE TIMESTAMP >= DATEADD(day, -7, CURRENT_TIMESTAMP())
  AND SPAN_TYPE = 'GENERATION'
GROUP BY USER_ID
ORDER BY total_cost DESC;

查询自定义元数据

SELECT
  TRACE_ID,
  METADATA:department::STRING as department,
  METADATA:quarter::STRING as quarter,
  TOTAL_COST,
  TOTAL_TOKENS
FROM OPENROUTER_TRACES
WHERE METADATA:department IS NOT NULL
  AND SPAN_TYPE = 'GENERATION'
ORDER BY TIMESTAMP DESC;

元数据映射

键	Snowflake 映射	说明
trace_id	TRACE_ID 列 / METADATA:trace_id	自定义 trace 标识符
trace_name	METADATA:trace_name	自定义 trace 名称
span_name	METADATA:span_name	中间 span 名称
generation_name	METADATA:generation_name	LLM 生成名称

user → USER_ID 有类型列；session_id → SESSION_ID 有类型列；trace 中所有自定义键 → METADATA VARIANT 列。

Privacy Mode

当为此目的地开启 Privacy Mode 时，prompt 和 completion 内容（INPUT/OUTPUT 列）不写入 Snowflake。其他 trace 数据仍正常写入。

常见问题

Q: 如何找到 Snowflake 账号标识符？

A: 在 Snowflake 实例 URL 中查找，格式为 https://app.snowflake.com/{region}/{account_id}。账号标识符 = {account_id}.{region}，例如 URL 为 https://app.snowflake.com/us-east-1/eac52885 时，账号标识符为 eac52885.us-east-1。

Q: 如何对频繁查询的元数据字段提升性能？

A: 可以在 Snowflake 中对 VARIANT 列的常用路径创建物化视图（Materialized View）或计算列（Virtual Column）。例如，如果你经常按 department 过滤，可以提取为独立列。也可以使用 Snowflake 的 CLUSTER BY 对常用过滤列做微分区优化。

Q: Snowflake 集成和 S3 集成有什么选型差异？

A: Snowflake 适合需要直接用 SQL 做 LLM 指标分析、与业务数据 JOIN、或构建 BI 仪表盘的场景；S3 更适合原始数据归档、与其他 ETL 工具集成、或成本敏感的存储场景（S3 比 Snowflake 便宜）。两者不互斥，可同时配置。