帮你快速理解、总结文档立即下载
文档中心>腾讯云数据仓库 TCHouse-C>Agent 数据工程>接入指南>Trace 接入

Trace 接入

最近更新时间：2026-08-21 10:27:30
我的收藏

本页目录：

步骤一、进入 Langfuse，完成账号注册与登录

1. 完成 Agent 数据工程服务实例开通后，在 Agent 数据工程服务实例列表页，单击进入 Langfuse，进入 Langfuse 首页。

2. 注册/登录您的 Langfuse 账号。


步骤二、进入 Langfuse，创建您的 Organization 和 Project

1. 单击 New Organization。

2. 输入组织名称，单击 Create 创建组织。

3. 输入项目名，单击 Create 创建项目。


步骤三、创建 API Key

1. Langfuse API Key 用于将 Agent Trace 数据投递至 Langfuse，单击 Create new API Key 创建新的 API Key。

警告：
您的 Secret Key 只会展示一次，请妥善保存。若遗忘，则需要创建新的 API Key。
您可以单击页面左下方的 Settings 按钮，进入设置页面，管理您的 API Key。


步骤四、完成 Langfuse 接入

Langfuse 可以与腾讯混元、OpenAI、Anthropic 等模型提供商无缝集成。以下以腾讯混元为例，介绍如何投递第一条 Agent Trace 数据。
1. 安装 Langfuse SDK：
pip install langfuse openai
2. 创建环境变量。
将 Langfuse API Key、Langfuse 服务端点设置为环境变量，用于指定 SDK 上报数据的 Langfuse 项目。
将腾讯云 TokenHub API Key 设置为环境变量，用于调用腾讯混元大模型服务。
# 在这里导入刚刚创建的 API Key 相关信息
export LANGFUSE_HOST="http://..."   # 填写您 Langfuse 的 Base URL
export LANGFUSE_PUBLIC_KEY="pk-lf-..."   # 填写您的 LANGFUSE_PUBLIC_KEY
export LANGFUSE_SECRET_KEY="sk-lf-..."   # 填写您的 LANGFUSE_SECRET_KEY
export HUNYUAN_API_KEY="sk-xxx..."    # 在腾讯云 TokenHub 控制台获取 API_KEY
3. 创建 langfuse_start.py 文件，写入以下代码：
import os
from langfuse import Langfuse
from langfuse.openai import OpenAI

# 1. 初始化 Langfuse
langfuse = Langfuse(
    host=os.getenv("LANGFUSE_HOST"),
    public_key=os.getenv("LANGFUSE_PUBLIC_KEY"),
    secret_key=os.getenv("LANGFUSE_SECRET_KEY"),
)

# 2. 用 Langfuse 包装的 OpenAI 客户端指向混元
client = OpenAI(
    base_url="https://tokenhub.tencentmaas.com/v1",
    #国内地区备用base_url: https://tokenhub.tencentmaas.cn/v1
    #国际地区base_url: https://tokenhub-intl.tencentmaas.com/v1
    api_key=os.getenv("HUNYUAN_API_KEY"),
)

# 3. 发起一次 LLM 调用（会自动被 Langfuse 追踪）
response = client.chat.completions.create(
    model="hy3",
    messages=[{"role": "user", "content": "你好，用一句话介绍一下你自己"}],
    temperature=0.7,
)

print(response.choices[0].message.content)

# 4. 确保数据全部上报
langfuse.flush()
print("✅ trace 已上报，去 Langfuse → Tracing 查看")
说明：
API Key 的使用可参考：腾讯云 TokenHub API 使用说明。
4. 运行 langfuse_start.py 文件：
# 请确保在设置了环境变量的同一终端窗口中运行该命令
python langfuse_start.py
5. 返回示例：
你好！我是腾讯混元 Hy3，基于大规模预训练与强化学习打造的多模态大语言模型，擅长中文理解、逻辑推理与复杂任务执行。

✅ trace 已上报，去 Langfuse → Tracing 查看

步骤五、在 Langfuse 中查看投放的数据

1. 在 Langfuse 中查询您的 Agent Trace 数据，已投放的 Trace 会按时间倒序展示在列表中。
2. 单击 Trace 可查看 Trace 详情。


步骤六、查看数据落盘情况

1. 投放 Trace 后等待落盘。
2. 在您的 Agent 数据工程服务实例的 TCHouse-C 集群中可查询您的 Trace 记录。
在 traces 表中，按 trace_id 可查到对应 Trace 记录。

在 observations 表中：
按 trace_id 可查到对应的 Generation + Span 记录：

可查看嵌套层级：

可查询 name / type / start_time / end_time / input / output / usage / metadata / level 等关键字段：

中国站