Langfuse 是开源 AI（Artificial Intelligence，人工智能）工程平台，提供 Agent（智能体）调用链路采集、Prompt（提示词）管理和评估等能力。ByteHouse（云数仓版）提供全托管的 Langfuse 服务。本文介绍服务开通、账号与组织授权、API Key（Application Programming Interface Key，应用程序编程接口密钥）配置，以及应用接入和 UI（User Interface，用户界面）中的基本查看流程。核心功能的详细用法请参见 Langfuse 官方文档。

ByteHouse（云数仓版）Langfuse 现处于公测期，请提工单或联系 ByteHouse 团队申请试用。各地域的支持情况如下：

ByteHouse 云数仓版的完整地域信息，请参见地域说明。

• 登录火山引擎控制台，进入目标地域下的 ByteHouse（云数仓版）新版控制台，确认目标环境，并准备需要绑定的计算组。
• 准备已授权 ByteHouseFullAccess 或 ByteHouseAccountAdminAccess 策略的 IAM 账号，用于在 ByteHouse 控制台开通和管理 Langfuse 服务。未授权上述任一策略的账号仅具有只读权限，不能执行开通、退订、创建、编辑或删除等写操作。
• 准备需要接入的应用，应用可使用能够连通的私网或公网地址，使用公网时，准备可绑定的公网 IP 和访问来源的出口地址段。

1. 在 ByteHouse（云数仓版）新版控制台中，确认目标地域和环境，在左侧导航栏选择 Agent可观测 > Langfuse。
2. 单击立即开通，在开通 Langfuse弹窗中核对初始化说明和软件版本，选择需要绑定的计算组，再单击确认开通。
   
3. 提交后，实例状态变为创建中。等待状态进入运行中后，再按需配置组织、项目、用户等其他资源。

   说明

   • 开通时，系统将初始化默认组织 default_org、默认项目 default_project，以及专用数据库账号和存储表。
   • 组织与项目属于 Langfuse 内部资源；专用数据库账号用于管理 Langfuse 相关数据表（events_full、scores 等）。
   • 如实例创建失败，可将鼠标悬停在失败状态上查看原因，并根据提示处理后重试。
4. 在网络设置区域，单击公网域名后的去绑定，​在绑定公网 IP抽屉中，选择一个可用的弹性公网 IP 后单击确认，等待绑定完成。

   说明

   公网 IP 绑定并完成白名单配置后，如果单击公网域名仍无法访问，可尝试清除访问端电脑的 DNS（Domain Name System，域名系统）缓存后重新访问。不同操作系统的清除方法，请参见无法通过公网域名访问。

5. 在网络设置中单击白名单配置，在IP 地址中填写访问来源地址段。

   说明

   • 白名单是应用上报和 UI 访问的必需配置，公网与私网共用同一份白名单。
   • 服务开通后默认未配置来源地址段，需要手动添加。
   • 应用上报需覆盖应用运行环境的来源地址段；UI 访问需覆盖浏览器所在网络的出口公网地址段。
6. （可选）换绑计算组。
   1. 在实例信息 > 基本信息区域单击换绑计算组。
   2. 在弹窗中核对当前绑定计算组，选择目标计算组。
   3. 确认已安排业务低峰期后，单击确认换绑。换绑需要重启 Langfuse 服务；完成后重新核对实例状态和计算组。

准备登录账号和项目访问权限 #

确认实例处于运行中，已完成公网 IP 绑定和白名单配置，浏览器能够打开公网域名。

1. 在 ByteHouse 控制台的用户及登录管理页确认邮箱登录已启用，单击创建用户，填写用户名、邮箱和初始密码后创建账号，核对用户状态为可用。
   
2. 在组织管理页找到目标组织，单击成员管理 > 添加成员，选择已创建的用户，并根据实际职责分配角色。
   

完整的用户维护与登录配置见管理用户和登录方式；成员和角色维护见管理组织和成员。

登录 UI 并进入项目 #

1. 在实例信息 > 网络设置中单击公网域名。
2. 在 Sign in to your account（登录账号）页填写 Email（邮箱）和 Password（密码），单击 Sign in（登录）。
3. 在 Organizations（组织）页面找到目标组织下的目标项目，单击 Go to project（进入项目），进入 Home（首页）。
   

完成基本接入后，可按需维护登录用户、组织成员、项目密钥、实例网络和计算资源。操作前请核对目标地域、环境及资源。

管理用户和登录方式 #

在 Langfuse 中，用户是登录和使用平台的个人账号。登录方式用于验证用户身份，例如邮箱密码登录或 SSO（Single Sign-On，单点登录）。用户能够访问哪些组织和项目，取决于其加入的组织及所分配的角色。

创建和维护用户 #

1. 在 Langfuse 服务页面选择用户及登陆管理，单击创建用户。
2. 在创建 Langfuse 用户弹窗中填写用户名、邮箱、初始密码和确认初始密码。当前仅支持创建邮箱登录用户。
   
3. 已创建的邮箱用户可重置密码或删除，SSO 用户仅提供删除操作。
   

   说明

   直接重置密码会立即使原密码失效。删除用户后，该用户将无法继续访问其绑定组织下的 Langfuse 项目。

变更登录方式 #

在用户及登录管理页，通过登录管理 > 变更配置调整 Langfuse 的登录方式。可仅开启邮箱登录、仅开启 SSO，或同时开启两种方式；需至少保留一种登录方式。
变更登录方式需重启 Langfuse 服务才能生效。​关闭某种登录方式后，对应类型的既有用户会被禁用，账号记录保留。组织成员关系和角色仍需在组织管理 > 成员管理中单独维护。

配置 SSO 登录 #

SSO（Single Sign-On，单点登录）通过企业统一身份服务验证用户身份。当前配置界面提供 OIDC（OpenID Connect，开放身份连接协议）登录类型。管理员完成身份提供方的应用注册并获取配置参数后，可在 ByteHouse 控制台启用 SSO。
操作步骤

1. 准备配置参数：​从企业身份提供方获取 Langfuse 应用的客户端 ID、客户端密钥和 OIDC 颁发者地址。应用注册、回调地址及用户声明的配置要求，请参见为 Langfuse 配置 OIDC 单点登录。
2. 启用 SSO：​在用户及登录管理 > 登录管理中单击变更配置，勾选 SSO，选择 OIDC 登录类型，并填写上述参数。按需保留邮箱登录。
   
3. 保存并重启：​单击保存，按提示单击确认重启，等待服务重启完成后核对 SSO 已启用。
4. 验证登录与授权：​重新打开 Langfuse UI，从 SSO 登录入口完成企业身份认证。

管理组织和成员 #

组织是 Langfuse 中管理团队协作的单位，一个组织可以包含多个项目。成员是加入该组织的用户，其角色决定在组织及下属项目中的操作权限。同一用户可以加入多个组织，并在不同组织中拥有不同角色。

查看或管理组织 #

1. 进入组织管理页。页面展示组织 ID、组织名称、创建时间、项目数、成员数和操作。
2. 如需新建组织，单击创建组织，输入组织名称并提交。
3. 在目标组织的操作列中，单击编辑修改组织名称，或直接单击成员管理维护成员。
4. 如需删除组织，需先将组织内的项目删除，再单击操作列更多的删除。删除操作不可撤销。
   

添加或移除组织成员 #

1. 在目标组织的操作列单击成员管理，打开右侧抽屉。列表展示用户名、邮箱、角色和操作，可按用户名或邮箱搜索。尚未添加成员时，列表为空。
2. 单击添加成员，在展开的表单中先选择已注册的 Langfuse 用户；选项以“用户名（邮箱）”显示。再选择角色，当前选项为 OWNER、ADMIN、MEMBER 和 VIEWER。这是用户在该组织中的角色，需根据实际职责选择。
3. 单击确认。成员添加后，核对列表中的用户名、邮箱和角色。该用户回到 Langfuse UI 的 Organizations（组织）页面后，应能看到已加入的组织及可访问的项目。
4. 需要调整角色时，单击角色旁的编辑图标；需要撤销组织访问时，在操作列单击移除。

管理项目和 API Key #

项目是 Langfuse 中管理应用数据的基本单位，用于组织调用链路、评估结果和提示词等，每个项目属于一个组织。项目成员权限继承所属组织的角色，不在项目中单独分配。
API Key 是应用调用 Langfuse API 时使用的认证凭据，由 Public Key（公开密钥）和 Secret Key（私密密钥）组成。本节中的密钥绑定到项目，供应用上报或访问该项目数据。

创建或维护项目 #

1. 进入项目管理页，通过归属组织筛选目标项目。展开项目可查看 API Key。
2. 需要新建项目时，单击创建项目，选择组织并填写名称后提交。
   
3. 项目创建后，可在操作列编辑项目、创建 API Key 或删除项目。

创建 API Key #

1. 在项目管理页，找到目标项目的操作列单击创建 API Key。
2. 在新建 API Key弹窗中填写API Key 名称。
3. 单击创建。
4. 出现创建成功后，弹窗展示 Secret Key 和 Public Key。请在关闭弹窗前保存完整 Secret Key；也可以下载 CSV 文件进行保存。
   

保存 API Key 后，可参见Python SDK 与 OpenTelemetry 接入说明完成应用接入和调用链路上报。

查看负载监控 #

服务运行中时，可在负载监控页面查看 Langfuse Web、Langfuse Worker、PostgreSQL和Redis的资源使用情况，当Langfuse UI 出现页面响应变慢、上报数据延迟显示或后台任务处理延迟时，可结合问题发生时间、应用请求量和任务执行情况查看这些指标，定位需要进一步排查的组件。各组件支持的监控指标如下。

退订 Langfuse 服务 #

不再需要使用 Langfuse 服务时，可以在实例信息页退订实例。操作账号需已授权 ByteHouseFullAccess 或 ByteHouseAccountAdminAccess 任一策略。

1. 进入目标地域和环境下的 Langfuse > 实例信息页，在基本信息区域，单击实例名称右侧的退订。
2. 在弹窗中核对影响范围。确认后，单击确定退订；如需放弃操作，单击取消。
   

实例状态显示失败 #

将鼠标悬停在失败状态上查看失败原因。根据提示检查计算组、资源和权限条件后重试；如无法恢复，保留失败信息并联系技术支持。

无法通过公网域名访问 #

先确认当前地域、环境和实例，检查公网域名是否已绑定及实例是否运行中；再检查域名解析、访问端代理或防火墙、公网 IP 与访问规则，以及浏览器或应用出口地址段的白名单配置。单个地址需使用带掩码的形式，例如 192.0.2.10/32。

若公网 IP 已绑定、实例处于运行中且访问来源已加入白名单，仍无法打开公网域名，可尝试清除访问端电脑的 DNS 缓存。本地缓存可能仍保留旧解析地址或此前“域名不存在”的查询结果；清除后，后续访问可以重新查询域名。根据本地操作系统选择以下方法。

ipconfig /flushdns

sudo killall -HUP mDNSResponder

sudo resolvectl flush-caches

执行后，重新打开公网域名。若仍无法访问，可退出并重新启动浏览器后重试。上述操作不会清除上游 DNS 服务器的缓存；若问题持续，请继续检查域名解析和网络访问规则，并保留错误信息及发生时间，联系技术支持。

域名可打开后，按登录 UI 并进入项目配置访问。登录失败检查账号和凭据；登录后无法进入项目，检查组织成员关系及角色。

应用已上报但看不到 Trace #

依次检查实例 Host、项目 Public Key 和 Secret Key、上报时间及 SDK 返回的错误。确认 API Key 未被删除，并在正确组织和项目的 Tracing 页面中选择包含上报时间的时间范围；检查 Search 和 Filters 是否排除了该请求。

SSO 登录失败并显示 NextAuth.js 错误 #

关闭 SSO 后，若继续使用之前的 SSO 登录入口，认证返回 Langfuse 时可能出现以下错误：

Error: This action with HTTP GET is not supported by NextAuth.js

出现该错误时，请检查当前实例是否仅开启了邮箱登陆方式：

1. 在 ByteHouse 新版控制台进入目标环境的 Langfuse > 用户及登录管理页，查看登录管理中是否勾选 SSO。
2. 若仅开启了邮箱登录，重新打开 Langfuse UI，使用已创建且状态为可用的邮箱账号登录。需要使用 SSO 时，按“配置 SSO 登录”启用 SSO，保存并确认重启，待新配置生效后重新登录。
3. 若 SSO 已开启，确认配置变更后已完成重启。仍无法登录时，核对身份提供方的配置与回调地址，保留错误消息及发生时间，联系技术支持。

调用链路查看及其他 Langfuse 功能的详细用法，请参见以下官方文档。

• 可观测概述：介绍调用链路采集、调用步骤及运行信息的查看。
• 调用链路检索：介绍按字段、条件和关键词筛选、检索调用记录。
• 指标与分析：介绍调用量、延迟、成本和质量等指标的分析。
• 自定义看板：介绍创建自定义图表和看板，集中查看应用指标。
• 数据集：介绍组织测试样本，并使用数据集开展应用实验和评估。
• 提示词管理入门：介绍提示词创建、版本管理及在应用中使用提示词。
• 用户追踪：介绍按应用用户标识查看调用记录、用量和反馈。
• 会话追踪：介绍关联多轮调用，并查看同一会话中的请求。
• 评估概述：介绍通过评分、评估器和实验评估应用输出质量。
• 告警：介绍应用指标的告警规则配置和通知流程。