步骤一、进入 Langfuse，完成账号注册与登录
1. 完成 Agent 可观测实例开通后，在 Agent 可观测实例列表页，点击「进入 Langfuse」，进入 Langfuse 首页。
2. 注册/登录您的 Langfuse 账号。
步骤二、进入 Langfuse，创建您的 Organization 和 Project
1. 单击 New Organization。
2. 输入组织名称，单击 Create 创建组织。
3. 输入项目名，单击 Create 创建项目
步骤三、创建 API Key
1. Langfuse API Key 用于将可观测数据投递至 Langfuse，单击 Create new API Key 创建新的 API Key。
警告：
您的 Secret Key 只会展示一次，请妥善保存。若遗忘，则需要创建新的 API Key。
您可以单击页面左下方的 Settings 按钮，进入设置页面，管理您的 API Key。
步骤四、完成 Langfuse 接入
Langfuse 可以与腾讯混元、OpenAI、Anthropic 等模型提供商无缝集成。以下以腾讯混元为例，介绍如何投递第一条可观测数据。
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 URLexport LANGFUSE_PUBLIC_KEY="pk-lf-..." # 填写您的 LANGFUSE_PUBLIC_KEYexport LANGFUSE_SECRET_KEY="sk-lf-..." # 填写您的 LANGFUSE_SECRET_KEYexport HUNYUAN_API_KEY="sk-xxx..." # 在腾讯云 TokenHub 控制台获取 API_KEY
3. 创建 langfuse_start.py 文件，写入以下代码：
import osfrom langfuse import Langfusefrom langfuse.openai import OpenAI# 1. 初始化 Langfuselangfuse = 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/v1api_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 查看")
说明：
4. 运行 langfuse_start.py 文件：
# 请确保在设置了环境变量的同一终端窗口中运行该命令python langfuse_start.py
5. 返回示例：
你好！我是腾讯混元 Hy3，基于大规模预训练与强化学习打造的多模态大语言模型，擅长中文理解、逻辑推理与复杂任务执行。✅ trace 已上报，去 Langfuse → Tracing 查看
步骤五、在 Langfuse 中查看投放的数据
1. 在 Langfuse 中查询您的 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 等关键字段：
