创建Langfuse-云数据库 ClickHouse-阿里云帮助中心

Langfuse是云数据库 ClickHouse 企业版提供的Agent可观测性功能，基于ClickHouse+Langfuse构建。通过全链路追踪、提示词管理和自动化评测能力，帮助企业实现Agent行为可追溯、成本可量化、效果可评估，解决Agent在生产环境中面临的输出不可控、成本不可见、风险不确定等问题。本文介绍如何开启Langfuse服务并投递第一条可观测数据。

说明

关于Langfuse的功能和使用场景，请参见什么是Langfuse。

前提条件

Python需要为3.9或以上版本。
已创建云数据库 ClickHouse 企业版实例，用于为Langfuse服务存储LLM可观测数据。具体操作，请参见新建企业版集群。
目前Langfuse服务处于邀测阶段，请填写表单申请开启Langfuse。具体操作，请参见【邀测公告】云数据库 ClickHouse 企业版Langfuse功能开启邀测。
开启Langfuse前，请将云数据库 ClickHouse 企业版实例的时区设置为UTC时区。可在云数据库 ClickHouse 企业版控制台的参数管理页面修改时区，具体操作请参见配置config.xml参数。
重要
修改时区对ClickHouse实例上的所有库表生效。若实例上已有存量库表，请确认修改时区不会影响现有查询和写入逻辑。否则，建议新建ClickHouse实例。

快速入门

步骤一：开启Langfuse

登录云数据库ClickHouse控制台。
在集群列表页面，选择企业版实例列表，单击目标实例ID，进入实例详情页。
在实例详情页左侧导航栏，单击Langfuse。
在弹出的对话框中，单击确定，开启Langfuse。

说明

服务开启时间预计10～20分钟，开启成功后，可以在Langfuse页面查看服务的详细信息，包括实例版本、VPC地址、公网地址及服务的白名单设置等。
服务会在云数据库 ClickHouse 企业版实例中新建存储可观测数据使用的数据库表和用户，并且会将服务的IP列表加入实例的访问白名单。

步骤二：配置白名单

首次进入Langfuse服务页面，需要先将您本机的IP加入Langfuse服务白名单列表。

待实例状态变为运行中，请确认控制台上弹框内显示的IP地址是否为您本机地址，若是则单击确定，若不是则需要手动添加白名单。

步骤三：创建用户

单击公网地址进入Langfuse服务页面。
首次进入，请单击Sign up，输入姓名、电子邮箱和密码创建Langfuse用户。

步骤四：创建组织与项目

您可以在页面上方进入已有的组织，或参见以下操作步骤创建新的组织。

单击New Organization。
输入组织名称，单击Create创建组织。
单击Next。
输入项目名，单击Create创建项目。

步骤五：创建API Key

Langfuse API Key用于将可观测数据投递至Langfuse。

单击Create new API Key创建新的API Key。

重要

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

步骤六：投递第一条可观测数据

Langfuse可以与阿里云百炼、OpenAI、Anthropic等模型提供商无缝集成。以下以阿里云百炼为例，介绍如何投递第一条可观测数据。

安装Langfuse SDK。
```
pip install langfuse
```
设置环境变量。
将Langfuse API Key、Langfuse服务端点设置为环境变量，从而指定SDK写入的Langfuse项目。将阿里云百炼API Key设置为环境变量，从而运行应用程序调用阿里云百炼模型服务。
说明
投递前，请确保SDK所在的主机IP已经加入Langfuse服务白名单。
```
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_BASE_URL="http://{your_langfuse_endpoint}:3000"
export DASHSCOPE_API_KEY="sk-..."
```

创建quick_start.py文件，写入以下代码。

import os
from langfuse.openai import OpenAI

try:
    client = OpenAI(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    )

    completion = client.chat.completions.create(
        model="qwen-plus",
        messages=[
            {'role': 'system', 'content': 'You are a helpful assistant.'},
            {'role': 'user', 'content': '你是谁？'}
        ]
    )
    print(completion.choices[0].message.content)
except Exception as e:
    print(f"错误信息：{e}")
    print("请参考文档：https://help.aliyun.com/zh/model-studio/error-code")

运行quick_start.py，可观测数据将会投递到Langfuse服务。
```
python quick_start.py
```
返回示例：
```
你好！我是通义千问（Qwen），阿里巴巴集团旗下的超大规模语言模型。我能够回答问题、创作文字，比如写故事、写公文、写邮件、写剧本、逻辑推理、编程等等，还能表达观点，玩游戏等。如果你有任何问题或需要帮助，欢迎随时告诉我！
```
您可以在Langfuse服务页面查看投递的可观测数据。
在 Langfuse 服务页面左侧导航栏选择 Observability > Tracing，可看到名为 OpenAI-generation 的 Trace 记录。单击某条 Trace，右侧详情面板 Preview 标签页展示对话内容（System：You are a helpful assistant.、User 消息及 Assistant 回复），下方 Metadata 区域展示 telemetry.sdk.name: opentelemetry、langfuse-sdk 4.5.0 等元数据信息。