LLMOps——Langfuse

Langfuse是什么？

Langfuse 是一个开源的 LLM（大语言模型）工程平台，专为开发者和团队设计，提供从调试、监控到评估的全方位支持。相比于 LangSmith，Langfuse 在灵活性、成本控制和自定义能力方面具有明显优势。以下是对 Langfuse 的详细介绍、其主要特性，以及为何选择 Langfuse 而非 LangSmith 的原因。(langfuse.com)

Langfuse 的核心特性

1. 开源与自托管支持

• 开源许可：Langfuse 采用 MIT 许可证，允许用户自由查看、修改和部署代码。这为需要高度定制化或对数据隐私有严格要求的组织提供了极大的灵活性。

• 自托管能力：支持通过 Docker 快速部署，适用于本地开发、私有云或企业内部服务器。这对于处理敏感数据或需要符合特定合规要求（如 HIPAA、PCI）的企业尤为重要。 (biggo.com)

2. 全面的可观测性与调试工具

• 调用链追踪：能够详细记录 LLM 应用的执行流程，包括 API 调用、嵌套链路和上下文信息，帮助开发者快速定位和解决问题。 (ycombinator.com)

• 性能指标监控：实时跟踪成本、延迟、质量等关键指标，并支持按用户、会话、功能、模型和提示版本等维度进行分析。 (ycombinator.com)

3. 提示管理与评估功能

• 提示版本控制：支持对提示进行版本管理，便于团队协作和实验对比。内置的提示实验功能允许在不同数据集上测试和比较提示效果。 (reddit.com)

• 评估机制：提供自动化评估（如 LLM-as-a-Judge）、用户反馈收集和手动标注等多种方式，帮助衡量和提升模型输出质量。 (ycombinator.com)

4. 广泛的集成与兼容性

• 多语言 SDK：提供 Python 和 TypeScript 的 SDK，支持与 OpenAI、LangChain、LlamaIndex、Haystack 等主流框架和工具的集成。 (github.com)

• API 优先设计：所有功能均可通过 API 访问，便于与现有系统集成，满足不同开发需求。

---

Langfuse vs LangSmith

✅ 选择 Langfuse 的理由

1. 完全开源：相比于 LangSmith 的闭源模式，Langfuse 的开源特性使其更适合需要高度定制化和数据控制的项目。

2. 自托管能力：Langfuse 支持免费自托管，而 LangSmith 的自托管需要购买企业许可证，成本较高。 (langfuse.com)

3. 更低的成本门槛：Langfuse 提供免费层和更灵活的定价策略，适合初创企业和个人开发者。

4. 广泛的集成支持：Langfuse 与多种 LLM 框架和工具兼容，适用于多样化的开发环境。

5. 活跃的社区支持：Langfuse 拥有活跃的开发者社区，用户可以通过 GitHub 讨论区和 Discord 获取支持和反馈。 (github.com)

🤔 为什么不选择 LangSmith？

• 闭源限制：LangSmith 是闭源产品，限制了用户对其进行深入定制和扩展的能力。

• 高昂的企业费用：LangSmith 的企业计划起价为 $75,000，且不支持初创企业和个人开发者，成本较高。 (lunary.ai)

• 集成限制：LangSmith 主要与 LangChain 框架集成，其他框架的集成可能较为复杂。

• 用户体验问题：有用户反馈 LangSmith 的仪表板界面混乱，配置复杂，影响使用体验。 (lunary.ai)

适用场景

• 需要自托管的企业：对于对数据隐私和合规性有严格要求的组织，Langfuse 的自托管能力提供了更高的安全性。

• 多框架集成需求：如果项目涉及多种 LLM 框架，Langfuse 的广泛集成支持可以满足多样化的开发需求。

• 成本敏感的项目：对于预算有限的初创企业或个人开发者，Langfuse 提供了更低的成本门槛和免费使用选项。

Langfuse 作为一个开源、灵活且功能全面的 LLM 工程平台，适合需要高度定制化、自托管能力和多框架集成支持的项目。相比之下，LangSmith 虽然在与 LangChain 的集成方面表现出色，但其闭源性质、高昂的费用和集成限制可能不适合所有用户。

Langfuse 架构

Langfuse 的架构由多个组件组成，以支持高效的数据处理和存储：

• 应用容器：

  • Langfuse Web：提供用户界面和 API 服务。
  • Langfuse Worker：异步处理事件，减轻主应用的负载。(reddit.com)

• 存储组件：

  • PostgreSQL：处理事务性工作负载。
  • ClickHouse：高性能的 OLAP 数据库，用于存储追踪、观察和评分数据。
  • Redis/Valkey：用于事件队列和数据缓存。
  • S3/Blob 存储：用于持久化存储大对象，如输入输出数据和大规模导出。(reddit.com, langfuse.com)

• LLM API / 网关：某些功能依赖于外部 LLM API 或网关。(langfuse.com)

这种架构使 Langfuse 能够处理每秒数百个事件，确保高可靠性和性能。 (langfuse.com)

Langfuse 的最新稳定版本是 v3.0.0，于 2024 年 12 月 9 日发布。该版本引入了多项架构改进，包括：(data.safetycli.com, langfuse.com)

• 引入了新的 Worker 容器，异步处理事件，提升性能。
• 采用 ClickHouse 替代 PostgreSQL 处理分析型查询，提升查询速度。
• 使用 S3/Blob 存储持久化事件数据，确保数据可靠性。
• 集成 Redis 用于事件队列和缓存，减少数据库负载。(data.safetycli.com, langfuse.com, reddit.com)

Langfuse 仅依赖开源组件，可以在本地、云端或本地数据中心部署。

开始使用 Langfuse 追踪

步骤如下：

1. 在 Langfuse 中创建新项目
2. 注册 Langfuse 账号或自行部署 Langfuse
3. 创建一个新项目
4. 在项目设置中生成新的 API 凭据

Langfuse集成使用了 Langchain 的回调系统（Callback System）。

注意：追踪属性（trace attributes）必须设置在外围的 span 上。

安装：

pip install langfuse

示例代码：

from langfuse.langchain import CallbackHandlerfrom langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate# 初始化 Langfuse 回调处理器
langfuse_handler = CallbackHandler()# 创建 LLM 和提示模板
llm = ChatOpenAI(model_name="gpt-4o")
prompt = ChatPromptTemplate.from_template("Tell me a joke about {topic}")
chain = prompt | llm# 触发调用，并接入 Langfuse 追踪回调
response = chain.invoke({"topic": "cats"},config={"callbacks": [langfuse_handler]}
)

如需了解更多信息，请参阅 Langchain 集成文档。

部署langfuse

Langfuse 是开源的，并可以通过 Docker 进行自托管。

当你选择自托管 Langfuse 时，你运行的是和 Langfuse Cloud 完全相同的基础架构。阅读《为什么选择 Langfuse？》以了解更多背景。

小规模部署

你可以在虚拟机或本地使用 Docker Compose 部署 Langfuse。适合测试和低负载场景，不具备高可用、弹性扩容或备份能力。

生产级部署（推荐）

适用于高可用生产环境：

• Kubernetes（Helm）
• AWS（Terraform）
• Azure（Terraform）
• GCP（Terraform）
• Railway

最低基础设施要求

服务	最低要求
Langfuse Web 容器	2 CPU，4 GiB 内存
Langfuse Worker 容器	2 CPU，4 GiB 内存
PostgreSQL 数据库	2 CPU，4 GiB 内存
Redis/Valkey 实例	1 CPU，1.5 GiB 内存
ClickHouse	2 CPU，8 GiB 内存
Blob 存储	无服务器（S3 或兼容）或 MinIO（2 CPU，4 GiB 内存）

Docker Compose

对于高可用性和高吞吐量场景，我们推荐使用 Kubernetes（部署指南）。Docker Compose 方案不具备高可用性、自动扩容和备份功能。

基本依赖：

• git
• docker 和 docker compose —— 在 Mac 或 Windows 上使用 Docker Desktop

获取最新的 Langfuse 仓库副本：

git clone https://github.com/langfuse/langfuse.git
cd langfuse

更新 docker-compose.yml 文件中的密钥（secrets）【可选】，然后运行 Langfuse 的 Docker Compose：

docker compose up

观察容器启动及日志输出。大约 2-3 分钟后，langfuse-web-1 容器会输出 “Ready”。此时你就可以进行下一步操作了。

现在你可以开始使用了！在浏览器打开 http://localhost:3000 访问 Langfuse 的界面。
Kubernetes（Helm）

k8s

默认情况下，该 Helm chart 会部署 Langfuse 应用容器及其数据存储（架构概览）。你也可以选择指向已有的 PostgreSQL、Clickhouse 和 Redis 实例。

获取 langfuse-k8s Helm chart：

helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update

对于本地测试，values.yaml 文件中的预配置变量通常已足够。

如果你要向应用发送任何敏感数据，或计划长时间运行，建议根据需求修改 values.yaml 文件。

（可选）创建一个新的命名空间用于 Langfuse 部署，例如：

kubectl create namespace langfuse

将 Helm chart 安装到该命名空间：

helm install langfuse langfuse/langfuse -n langfuse

默认假设安装名称为 langfuse。如果你想使用其他名称安装，需要相应调整 values.yaml 中 Redis 的主机名。

此时，Kubernetes 会开始部署 Langfuse 应用及其依赖，可能需要最多 5 分钟。你可以通过以下命令监控部署进度：

kubectl get pods -n langfuse

预期所有 Pod 最终会运行起来。部署数据库时，langfuse-web 和 langfuse-worker 容器可能会重启几次。

简单测试 UI

默认情况下，Langfuse UI 通过 ClusterIP 服务提供。使用命令查看服务及端口映射：

kubectl get services -n langfuse

找到 langfuse-web 服务后，执行端口转发：

kubectl port-forward svc/langfuse-web -n langfuse <本地端口>:<节点端口>

然后在浏览器打开 http://localhost:<本地端口>，即可访问 UI。你可以注册账号，创建组织和项目，开始探索 Langfuse。

对于离线环境的同学也可以直接去github下载helm文件：

https://github.com/langfuse/langfuse-k8s

这是一个社区维护的仓库，包含了在 Kubernetes 上部署 Langfuse 的相关资源。

Langfuse 自托管文档：https://langfuse.com/self-hosting

仓库结构

• examples 目录包含示例的 YAML 配置文件
• charts/langfuse 目录包含用于部署 Langfuse 及相关数据库的 Helm chart

按照下面定义的要求，配置一个新的 values.yaml 文件中的必要密钥和参数。然后执行以下命令安装 Helm chart：

helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update
helm install langfuse langfuse/langfuse -f values.yaml

升级

helm repo update
helm upgrade langfuse langfuse/langfuse

请确认 Chart.yaml 中的子 chart 是否在版本间发生了更新。如果有，请按照对应子 chart 的升级指南进行升级。

默认情况下，chart 使用最小资源以保证稳定运行。生产环境建议调整 values.yaml 中的以下参数。完整配置请参考 Langfuse 文档。

langfuse:resources:limits:cpu: "2"memory: "4Gi"requests:cpu: "2"memory: "4Gi"clickhouse:resources:limits:cpu: "2"memory: "8Gi"requests:cpu: "2"memory: "8Gi"keeper:resources:limits:cpu: "2"memory: "4Gi"requests:cpu: "2"memory: "4Gi"redis:primary:resources:limits:cpu: "1"memory: "1.5Gi"requests:cpu: "1"memory: "1.5Gi"s3:resources:limits:cpu: "2"memory: "4Gi"requests:cpu: "2"memory: "4Gi"

需要设置的配置项：

# 可选但强烈推荐。通过 `openssl rand -hex 32` 生成。
# langfuse:
#   encryptionKey:
#     value: ""
langfuse: salt:value: secureSaltnextauth:secret:value: ""postgresql:auth:# 若使用 `postgres` 作为用户名，则需要提供 postgresPassword 而非 password。username: langfusepassword: ""clickhouse:auth:password: ""redis:auth:password: ""s3:auth:rootPassword: ""

也可以通过引用已有 Secret 设置（Secret 必须存在）：

# 可选但强烈推荐。通过 `openssl rand -hex 32` 生成。
# langfuse:
#   encryptionKey:
#     secretKeyRef:
#       name: langfuse-encryption-key-secret
#       key: encryptionKey
langfuse: salt:secretKeyRef:name: langfuse-generalkey: saltnextauth:secret:secretKeyRef:name: langfuse-nextauth-secretkey: nextauth-secretpostgresql:auth:# 若使用 `postgres` 作为用户名，则需在 secretKeys 中提供 adminPasswordKey。username: langfuseexistingSecret: langfuse-postgresql-authsecretKeys:userPasswordKey: passwordclickhouse:auth:existingSecret: langfuse-clickhouse-authexistingSecretKey: passwordredis:auth:existingSecret: langfuse-redis-authexistingSecretPasswordKey: passwords3:auth:# 若设置了 existingSecret，则 root 用户和 root 密码必须通过 Secret 提供existingSecret: langfuse-s3-authrootUserSecretKey: rootUserrootPasswordSecretKey: rootPassword

示例：使用外部 Postgres 服务器

postgresql:deploy: falseauth:username: my-usernamepassword: my-passworddatabase: my-databasehost: my-external-postgres-server.comdirectUrl: postgres://my-username:my-password@my-external-postgres-server.comshadowDatabaseUrl: postgres://my-username:my-password@my-external-postgres-server.com

示例：使用外部 S3 桶

s3:deploy: falsebucket: "langfuse-bucket"region: "eu-west-1"endpoint: "https://s3.eu-west-1.amazonaws.com"forcePathStyle: falseaccessKeyId:value: "mykey"secretAccessKey:value: "mysecret"eventUpload:prefix: "events/"batchExport:prefix: "exports/"mediaUpload:prefix: "media/"

使用自定义部署策略

langfuse:deployment:strategy:type: RollingUpdaterollingUpdate:maxSurge: 50%maxUnavailable: 50%

启用 ingress

langfuse:ingress:enabled: truehosts:- host: langfuse.your-host.compaths:- path: /pathType: Prefixannotations: []

自定义存储类定义：Langfuse chart 支持为所有持久卷配置存储类，可通过两种方式：

• 全局存储类（应用于所有持久卷，除非被覆盖）

  global:defaultStorageClass: "your-storage-class"
  

• 组件特定存储类（覆盖特定组件的存储类）

  postgresql:primary:persistence:storageClass: "postgres-storage-class"redis:primary:persistence:storageClass: "redis-storage-class"clickhouse:persistence:storageClass: "clickhouse-storage-class"s3:persistence:storageClass: "minio-storage-class"
  

若未指定存储类，将使用集群默认存储类。

使用带客户端证书的外部 Postgres 服务器，使用自定义 Secret 和额外环境变量映射

langfuse:salt: nullnextauth: secret: nullextraVolumes:- name: db-keystoresecret:secretName: langfuse-postgres  # 包含 server-ca.pem, sslidentity.pk12 等文件extraVolumeMounts:- name: db-keystoremountPath: /secrets/db-keystorereadOnly: trueadditionalEnv:- name: DATABASE_URLvalueFrom:secretKeyRef:name: langfuse-postgreskey: database-url- name: NEXTAUTH_SECRETvalueFrom:secretKeyRef:name: langfuse-generalkey: nextauth-secret- name: SALTvalueFrom:secretKeyRef:name: langfuse-generalkey: salt
postgresql:deploy: falseauth:password: nullusername: null

使用 hostAliases 进行覆盖：此配置会在所有 langfuse-web Pod 的 /etc/hosts 文件中添加一条记录，将对 “oauth.id.jumpcloud.com” 的请求转发到本地回环地址。

langfuse:web:hostAliases:- ip: 127.0.0.1hostnames:- "oauth.id.jumpcloud.com"

使用拓扑分布约束：将 Pod 均匀分布在不同可用区，提高高可用性：

langfuse:# 应用于所有 langfuse Pod 的全局拓扑分布约束pod:topologySpreadConstraints:- maxSkew: 1topologyKey: topology.kubernetes.io/zonewhenUnsatisfiable: ScheduleAnywaylabelSelector:matchLabels:app.kubernetes.io/instance: langfuse# 组件特定的拓扑分布约束web:pod:topologySpreadConstraints:- maxSkew: 1topologyKey: kubernetes.io/hostnamewhenUnsatisfiable: DoNotSchedulelabelSelector:matchLabels:app: webworker:pod:topologySpreadConstraints:- maxSkew: 1topologyKey: kubernetes.io/hostnamewhenUnsatisfiable: DoNotSchedulelabelSelector:matchLabels:app: worker

Configuration配置

Langfuse 提供了丰富的配置选项，均通过环境变量进行设置。这些环境变量需要传递给所有应用容器。

环境变量

Langfuse 支持通过环境变量对部署进行精细调控。Langfuse Web 和 Langfuse Worker 容器可以使用相同的环境变量。

变量	必填 / 默认值	描述
DATABASE_URL	必填	Postgres 数据库的连接字符串。也可以使用 DATABASE_HOST、DATABASE_USERNAME、DATABASE_PASSWORD、DATABASE_NAME 和 DATABASE_ARGS 替代。
DIRECT_URL	默认为 DATABASE_URL	用于数据库迁移的 Postgres 连接字符串。如果希望迁移时使用不同用户，或在 DATABASE_URL 上使用连接池，可配置此项。对于大型部署，请配置具有较长超时的数据库用户，因为迁移可能需要较长时间。
SHADOW_DATABASE_URL	可选	若数据库用户没有 CREATE DATABASE 权限，需手动创建 shadow 数据库并配置此项。常见于使用云数据库的情况，详见 Prisma 文档。
CLICKHOUSE_MIGRATION_URL	必填	ClickHouse 实例的迁移地址（使用 TCP 协议）。格式：clickhouse://<hostname>:(9000/9440)
CLICKHOUSE_MIGRATION_SSL	默认 false	是否通过 SSL 连接 ClickHouse 用于迁移。设为 true 可启用 SSL。
CLICKHOUSE_URL	必填	ClickHouse 实例的地址。格式：http(s)://<hostname>:(8123/8443)
CLICKHOUSE_USER	必填	ClickHouse 用户名，需具备 SELECT、ALTER、INSERT、CREATE、DELETE 权限。
CLICKHOUSE_PASSWORD	必填	ClickHouse 用户密码。
CLICKHOUSE_DB	默认值为 default	使用的 ClickHouse 数据库名称。
CLICKHOUSE_CLUSTER_ENABLED	默认 true	是否使用 ON CLUSTER 执行 ClickHouse 命令。单容器部署请设为 false。
LANGFUSE_AUTO_CLICKHOUSE_MIGRATION_DISABLED	默认 false	是否在启动时禁用 ClickHouse 自动迁移。
REDIS_CONNECTION_STRING	必填	Redis 实例的连接字符串。可选替代项为：REDIS_HOST、REDIS_PORT 和 REDIS_AUTH。TLS 配置详见缓存配置文档。
NEXTAUTH_URL	必填	Langfuse Web 部署的 URL，例如 https://yourdomain.com 或 http://localhost:3000，用于 OAUTH 认证。
NEXTAUTH_SECRET	必填	用于验证登录会话 Cookie。需通过 openssl rand -base64 32 生成至少 256 比特的密钥。
SALT	必填	用于对 API Key 加盐，需通过 openssl rand -base64 32 生成至少 256 比特的密钥。
ENCRYPTION_KEY	必填	用于加密敏感数据。必须为 256 位的十六进制字符串（64 个字符），可用命令 openssl rand -hex 32 生成。
LANGFUSE_CSP_ENFORCE_HTTPS	默认 false	若设为 true，将启用 CSP 头部，仅允许 HTTPS 连接。
PORT	默认 3000 / 3030	服务器监听的端口。Web 用 3000，Worker 用 3030。
HOSTNAME	默认 localhost	某些环境中需设置为 0.0.0.0 才能被容器外部访问（例如 Google Cloud Run）。

S3 事件上传配置

变量	必填	描述
LANGFUSE_S3_EVENT_UPLOAD_BUCKET	是	事件信息上传的 S3 存储桶名称。
LANGFUSE_S3_EVENT_UPLOAD_PREFIX	否	存储事件的路径前缀（可为空），必须以 / 结尾。
LANGFUSE_S3_EVENT_UPLOAD_REGION	否	存储桶所在区域。
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT	否	上传事件使用的 endpoint。
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID	否	存储桶访问密钥，需具备 List、Get、Put 权限。
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY	否	存储桶密钥。
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE	否	是否强制使用 path-style 请求。使用 MinIO 时必需。

S3 批量导出配置

变量	必填	描述
LANGFUSE_S3_BATCH_EXPORT_ENABLED	否，默认 false	是否启用批量导出功能，设为 true 可启用。
LANGFUSE_S3_BATCH_EXPORT_BUCKET	是	存储批量导出数据的存储桶名称。
LANGFUSE_S3_BATCH_EXPORT_PREFIX	否	批量导出文件的路径前缀，需以 / 结尾。
LANGFUSE_S3_BATCH_EXPORT_REGION	否	存储桶所在区域。
LANGFUSE_S3_BATCH_EXPORT_ENDPOINT	否	上传批量导出文件使用的 endpoint。
LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID	否	存储桶访问密钥。
LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY	否	存储桶密钥。
LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE	否	是否强制使用 path-style 请求。
LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT	否	用于生成预签名 URL 的外部 endpoint（可选）。不提供则使用主 endpoint。适用于需在 VPC 内部完成传输的情况。
BATCH_EXPORT_PAGE_SIZE	默认 500	流式导出时每页数据量，可根据内存优化进行调整。
BATCH_EXPORT_ROW_LIMIT	默认 1,500,000	单次批量导出最大行数。

S3 媒体上传配置

变量	必填	描述
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET	是	上传媒体文件使用的 S3 存储桶名称。
LANGFUSE_S3_MEDIA_UPLOAD_PREFIX	否	媒体存储路径前缀，需以 / 结尾。
LANGFUSE_S3_MEDIA_UPLOAD_REGION	否	存储桶所在区域。
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT	否	上传媒体使用的 endpoint。
LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID	否	存储桶访问密钥。
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY	否	存储桶密钥。
LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE	否	是否强制使用 path-style 请求（MinIO 必需）。
LANGFUSE_S3_MEDIA_MAX_CONTENT_LENGTH	默认 1GB	允许上传的最大媒体文件大小（字节）。
LANGFUSE_S3_MEDIA_DOWNLOAD_URL_EXPIRY_SECONDS	默认 3600	媒体文件预签名下载链接有效期（秒）。

其他设置

变量	默认值	描述
LANGFUSE_S3_CONCURRENT_WRITES	50	并发写入 S3 的最大数量。用于处理 socket 连接过多报错。
LANGFUSE_S3_CONCURRENT_READS	50	并发读取 S3 的最大数量。
LANGFUSE_AUTO_POSTGRES_MIGRATION_DISABLED	默认 false	是否禁用 PostgreSQL 自动迁移（不推荐）。
LANGFUSE_LOG_LEVEL	默认 info	应用日志级别：trace、debug、info、warn、error、fatal。
LANGFUSE_LOG_FORMAT	默认 text	日志格式：text 或 json。
LANGFUSE_LOG_PROPAGATED_HEADERS	可选	通过 OpenTelemetry Baggage 传播的 HTTP Header 名单，逗号分隔。例如：x-request-id,x-user-id。用于调试与可观测性。

额外功能

可以通过环境变量启用并配置以下附加功能：

• 身份验证与 SSO
• 自动访问授权
• 自定义基础路径
• 加密
• 无头初始化（Headless Initialization）
• 网络设置
• 组织创建者（企业版）
• 组织管理 API（企业版）
• 事务性邮件
• UI 自定义（企业版）

时区说明

Langfuse 假定其所有基础设施组件默认使用 UTC 时间。特别是 Postgres 和 ClickHouse 的任何覆盖 UTC 设置的配置都是不受支持的，可能会导致意外行为。如果你希望我们支持其他时区，请在 GitHub Discussion 中投票。

健康检查与就绪检查端点

Langfuse Web 提供 /api/public/health 健康检查端点 和 /api/public/ready 就绪检查端点，Langfuse Worker 提供 /api/health 健康检查端点。

访问方式示例：

# langfuse-web
curl http://localhost:3000/api/public/health
curl http://localhost:3000/api/public/ready# langfuse-worker
curl http://localhost:3030/api/health

健康检查端点的可能响应：

• 200 OK：API 正常运行，并成功连接数据库
• 503 Service Unavailable：API 不正常运行，或无法连接数据库

就绪检查端点的可能响应：

• 200 OK：应用已准备好接收流量
• 500 Internal Server Error：应用接收到 SIGTERM 或 SIGINT，建议不再接收流量

监控系统可以周期性调用这些端点以获取健康状态更新。

默认情况下，Langfuse Web 的健康检查不会验证数据库是否可用，因为在某些场景下数据库不可用但应用仍能提供服务。
若要强制执行数据库可用性检查，可添加参数：
?failIfDatabaseUnavailable=true，如：
curl http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true

OpenTelemetry 支持

Langfuse 使用 OpenTelemetry 提供应用可观测性。如果你希望将 Langfuse 集成至你自己的链路追踪系统中，可配置以下环境变量将追踪信息发送到自定义收集器：

变量	默认值 / 是否必需	描述
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4318	OTLP 收集器的地址。路径为 /v1/traces
OTEL_SERVICE_NAME	web/worker	在 APM 工具中的服务名称
OTEL_TRACE_SAMPLING_RATIO	1	追踪采样比例。1 表示发送全部追踪数据，取值范围为 0 到 1

基础设施

langfuse镜像

Langfuse 使用 Docker 来容器化应用程序。应用分为两个容器：

• Langfuse Web：提供 Langfuse 控制台和 API 的 Web 服务器。
• Langfuse Worker：负责后台任务，如发送邮件或处理事件。

生产环境建议为所有容器至少分配 2 个 CPU 和 4 GB 内存。为了高可用，Langfuse Web 容器应至少运行两个实例。自动扩容时，建议当任一容器 CPU 利用率超过 50% 时增加实例数。

Langfuse 容器中的 Node.js 应用需要适当配置内存限制以保证高效运行。默认情况下，Node.js 最大堆内存为 1.7 GiB，可能小于容器分配的实际内存（例如容器分配 4 GiB，但 Node.js 限制为 1.7 GiB，可能导致内存问题）。

正确配置内存限制的方式是在 Langfuse Web 和 Worker 容器中通过环境变量 NODE_OPTIONS 设置 max-old-space-size：

NODE_OPTIONS=--max-old-space-size=${var.memory}

推荐使用预构建的 Docker 镜像，也可以从源码自行构建：

# 克隆代码仓库
git clone https://github.com/langfuse/langfuse.git
cd langfuse# 切换到 production 分支
# main 分支包含未发布且可能不稳定的改动
git checkout production# 构建 web 镜像
docker build -t langfuse/langfuse -f ./web/Dockerfile .# 构建 worker 镜像
docker build -t langfuse/langfuse-worker -f ./worker/Dockerfile .

运行 Langfuse Web（更多环境变量配置见配置文档）：

docker run --name langfuse-web \-e DATABASE_URL=postgresql://hello \-e NEXTAUTH_URL=http://localhost:3000 \-e NEXTAUTH_SECRET=mysecret \-e SALT=mysalt \-e ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000 \  # 通过 openssl rand -hex 32 生成-e CLICKHOUSE_URL=http://clickhouse:8123 \-e CLICKHOUSE_USER=clickhouse \-e CLICKHOUSE_PASSWORD=clickhouse \-e CLICKHOUSE_MIGRATION_URL=clickhouse://clickhouse:9000 \-e REDIS_HOST=localhost \-e REDIS_PORT=6379 \-e REDIS_AUTH=redis \-e LANGFUSE_S3_EVENT_UPLOAD_BUCKET=my-bucket \-e LANGFUSE_S3_EVENT_UPLOAD_REGION=us-east-1 \-e LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE \-e LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=bPxRfiCYEXAMPLEKEY \-p 3000:3000 \-a STDOUT \
langfuse/langfuse:3

运行 Langfuse Worker：

docker run --name langfuse-worker \-e DATABASE_URL=postgresql://hello \-e SALT=mysalt \-e ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000 \  # 通过 openssl rand -hex 32 生成-e CLICKHOUSE_URL=http://clickhouse:8123 \-e CLICKHOUSE_USER=clickhouse \-e CLICKHOUSE_PASSWORD=clickhouse \-e REDIS_HOST=localhost \-e REDIS_PORT=6379 \-e REDIS_AUTH=redis \-e LANGFUSE_S3_EVENT_UPLOAD_BUCKET=my-bucket \-e LANGFUSE_S3_EVENT_UPLOAD_REGION=us-east-1 \-e LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE \-e LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=bPxRfiCYEXAMPLEKEY \-p 3030:3030 \-a STDOUT \
langfuse/langfuse-worker:3

ClickHouse

ClickHouse 是 Langfuse 中用于 Trace（追踪）、Observation（观察）和 Score（评分）实体的主要 OLAP 存储解决方案。它针对高写入吞吐量和快速分析查询进行了优化。本文介绍如何在 Langfuse 中配置 ClickHouse，并说明在自行部署 ClickHouse（可选）时需要注意的事项。

Langfuse 支持 ClickHouse 版本 >= 24.3。

Langfuse 接受以下环境变量，以便对 ClickHouse 的使用进行精细调控。这些变量需同时配置在 Langfuse Web 和 Langfuse Worker 容器中：

变量名	是否必需 / 默认值	描述
CLICKHOUSE_MIGRATION_URL	必需	ClickHouse 实例的迁移连接地址（TCP 协议）。格式：clickhouse://<hostname>:9000 或 :9440（SSL）
CLICKHOUSE_MIGRATION_SSL	false	若需通过 SSL 执行迁移，则设为 true
CLICKHOUSE_URL	必需	ClickHouse 实例的 HTTP(S) 地址。格式：http(s)://<hostname>:8123 或 8443
CLICKHOUSE_USER	必需	ClickHouse 数据库的用户名，需要具备 SELECT、ALTER、INSERT、CREATE、DELETE 权限
CLICKHOUSE_PASSWORD	必需	ClickHouse 用户的密码
CLICKHOUSE_DB	default	要使用的数据库名称
CLICKHOUSE_CLUSTER_ENABLED	true	是否在集群上运行命令（ON CLUSTER）。单容器部署请设为 false
LANGFUSE_AUTO_CLICKHOUSE_MIGRATION_DISABLED	false	是否禁用自动 ClickHouse 数据迁移

当 CLICKHOUSE_CLUSTER_ENABLED=true 时，Langfuse 默认使用 default 作为集群名称。你可以通过 CLICKHOUSE_CLUSTER_NAME 修改这个名称，但此时自动迁移将失效，必须手动执行迁移。步骤如下：

1. 克隆 Langfuse 仓库；
2. 修改 ./packages/shared/clickhouse/migrations/clustered/*.sql 中的集群名称；
3. 执行以下命令手动迁移：

cd ./packages/shared && sh ./clickhouse/scripts/up.sh

Langfuse 要求所有基础设施组件的默认时区为 UTC。特别是 Postgres 和 ClickHouse 的设置若偏离 UTC，可能会导致不可预期行为。如需支持其他时区，请在 GitHub Discussion 上留言投票。

用户权限

ClickHouse 用户（由 CLICKHOUSE_USER 指定）必须拥有以下权限：

GRANT INSERT ON default.* TO 'user';
GRANT SELECT ON default.* TO 'user';
GRANT ALTER UPDATE, ALTER DELETE ON default.* TO 'user';
GRANT CREATE ON default.* TO 'user';
GRANT DROP TABLE ON default.* TO 'user';

将 'user' 替换为实际用户名。如使用非 default 数据库，请同步调整数据库名。

部署选项

ClickHouse Cloud

ClickHouse Cloud 是一个可扩展、全托管的部署方式。可通过以下平台启动：

• AWS Marketplace
• Google Cloud Marketplace
• Azure Marketplace

ClickHouse Cloud 的集群部署在你的云环境之外，但支持私有连接（Private Link）。

示例配置：

CLICKHOUSE_URL=https://<identifier>.<region>.aws.clickhouse.cloud:8443
CLICKHOUSE_MIGRATION_URL=clickhouse://<identifier>.<region>.aws.clickhouse.cloud:9440
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=changeme
CLICKHOUSE_MIGRATION_SSL=true

故障排查

• 错误 driver: bad connection in line 0：
  请确保 CLICKHOUSE_MIGRATION_SSL=true 且 Web 容器能访问 ClickHouse。必要时检查 IP 白名单和 Private Link 配置。

• 错误 ON CLUSTER is not allowed for Replicated database.：
  Azure 上的 ClickHouse Cloud 不支持 ON CLUSTER + Replicated，建议设 CLICKHOUSE_CLUSTER_ENABLED=false。

ClickHouse on Kubernetes (Helm)

推荐使用 Bitnami 提供的 Helm Chart 进行 ClickHouse 的生产部署。

示例配置：

clickhouse:deploy: trueshards: 1  # 仅支持单分片replicaCount: 3resourcesPreset: largeauth:username: defaultpassword: changeme

• shards: 当前 Langfuse 不支持多分片，请设为 1。
• replicaCount: 每个分片副本数，建议至少 3。
• resourcesPreset: 推荐至少使用 large。
• disk: 请确保使用的 storage class 启用了 allowVolumeExpansion: true。

环境变量配置：

CLICKHOUSE_URL=http://<chart-name>-clickhouse:8123
CLICKHOUSE_MIGRATION_URL=clickhouse://<chart-name>-clickhouse:9000
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=changeme

扩容存储（NOT_ENOUGH_SPACE）

Kubernetes 中若磁盘空间不足，会报此错误。解决方法：

1. 查看磁盘使用情况：

kubectl get pvc -l app.kubernetes.io/name=clickhouse
kubectl exec -it <pod> -- df -h /var/lib/clickhouse

2. 扩展 PVC：

kubectl edit pvc data-<chart-name>-clickhouse-0
# 或批量扩容
kubectl patch pvc data-<chart-name>-clickhouse-0 -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}'

3. 修改 Helm 配置并升级：

clickhouse:persistence:size: 200Gi

helm upgrade <release-name> <chart-name> -f values.yaml

4. 监控扩容状态：

kubectl get pvc -w
kubectl exec -it <pod> -- df -h /var/lib/clickhouse

预防建议：

• 监控磁盘使用（推荐 80% 时报警）
• 使用支持扩容的存储类
• 使用自动扩容工具，如 volume-autoscaler
• 高增长场景可使用对象存储作为磁盘

Docker 部署

适用于开发环境（不推荐用于生产）。

示例命令：

docker run --name clickhouse-server \-e CLICKHOUSE_DB=default \-e CLICKHOUSE_USER=clickhouse \-e CLICKHOUSE_PASSWORD=clickhouse \-d --ulimit nofile=262144:262144 \-p 8123:8123 \-p 9000:9000 \-p 9009:9009 \clickhouse/clickhouse-server

环境变量配置：

CLICKHOUSE_URL=http://localhost:8123
CLICKHOUSE_MIGRATION_URL=clickhouse://localhost:9000
CLICKHOUSE_USER=clickhouse
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_CLUSTER_ENABLED=false

使用对象存储作为磁盘

ClickHouse 支持使用对象存储（如 AWS S3、Azure Blob、GCS）作为数据磁盘，用于实现自动扩容和增强持久性。

S3 示例

配置文件 config.xml：

<clickhouse><merge_tree><storage_policy>s3</storage_policy></merge_tree><storage_configuration><disks><s3><type>object_storage</type><object_storage_type>s3</object_storage_type><metadata_type>local</metadata_type><endpoint>https://s3.eu-central-1.amazonaws.com/example-bucket-name/data/</endpoint><access_key_id>ACCESS_KEY</access_key_id><secret_access_key>ACCESS_KEY_SECRET</secret_access_key></s3></disks><policies><s3><volumes><main><disk>s3</disk></main></volumes></s3></policies></storage_configuration>
</clickhouse>

或者使用环境变量凭据：

<use_environment_credentials>1</use_environment_credentials>

Docker Compose：

services:clickhouse:image: clickhouse/clickhouse-serveruser: "101:101"container_name: clickhousehostname: clickhouseenvironment:CLICKHOUSE_DB: defaultCLICKHOUSE_USER: clickhouseCLICKHOUSE_PASSWORD: clickhousevolumes:- ./config.xml:/etc/clickhouse-server/config.d/s3disk.xml:ro- langfuse_clickhouse_data:/var/lib/clickhouse- langfuse_clickhouse_logs:/var/log/clickhouse-serverports:- "8123:8123"- "9000:9000"volumes:langfuse_clickhouse_data:driver: locallangfuse_clickhouse_logs:driver: local

Azure Blob 示例

配置文件 config.xml：

<clickhouse><merge_tree><storage_policy>blob_storage_disk</storage_policy></merge_tree><storage_configuration><disks><blob_storage_disk><type>object_storage</type><object_storage_type>azure_blob_storage</object_storage_type><metadata_type>local</metadata_type><storage_account_url>http://azurite:10000/devstoreaccount1</storage_account_url><container_name>langfuse</container_name><account_name>devstoreaccount1</account_name><account_key>默认Azurite密钥</account_key></blob_storage_disk></disks><policies><blob_storage_disk><volumes><main><disk>blob_storage_disk</disk></main></volumes></blob_storage_disk></policies></storage_configuration>
</clickhouse>

Docker Compose 示例（含 Azurite）：

services:clickhouse:image: clickhouse/clickhouse-serveruser: "101:101"container_name: clickhousehostname: clickhouseenvironment:CLICKHOUSE_DB: defaultCLICKHOUSE_USER: clickhouseCLICKHOUSE_PASSWORD: clickhousevolumes:- ./config.xml:/etc/clickhouse-server/config.d/azuredisk.xml:ro- langfuse_clickhouse_data:/var/lib/clickhouse- langfuse_clickhouse_logs:/var/log/clickhouse-serverports:- "8123:8123"- "9000:9000"depends_on:- azuriteazurite:image: mcr.microsoft.com/azure-storage/azuritecontainer_name: azuritecommand: azurite-blob --blobHost 0.0.0.0

缓存（Redis/Valkey）

Langfuse 使用 Redis/Valkey 作为缓存层和队列，用于在 API 接收到新事件时快速响应，并延迟事件的处理与写入，从而帮助系统平稳应对请求高峰。

你可以选择在 AWS、Azure 或 GCP 上使用托管服务，或自行部署。最低要求为 Redis 7 版本，并且实例必须配置 maxmemory-policy=noeviction。

配置

Langfuse 支持通过以下环境变量对 Redis 的使用进行细致配置。Web 服务容器和 Worker 容器均需要设置这些变量。

使用连接字符串

变量名	是否必需	描述
REDIS_CONNECTION_STRING	必需	Redis 连接字符串，格式为：redis[s]://[[用户名][:密码]@][主机][:端口][/数据库编号]

或者使用独立变量

变量名	是否必需 / 默认值	描述
REDIS_HOST	必需	Redis 主机名
REDIS_PORT	默认：6379	Redis 实例端口
REDIS_AUTH	可选	Redis 实例的身份验证密码
REDIS_TLS_ENABLED	默认：false	是否启用 TLS，可通过 rediss:// 启用
REDIS_TLS_CA_PATH	可选	Redis TLS 连接的 CA 证书路径
REDIS_TLS_CERT_PATH	可选	Redis TLS 连接的客户端证书路径
REDIS_TLS_KEY_PATH	可选	Redis TLS 连接的私钥路径

部署选项

云服务商托管的 Redis/Valkey

AWS ElastiCache、Azure Cache for Redis 和 GCP Memorystore 都提供完全托管的 Redis 服务。Langfuse 支持读副本间的故障转移，但目前不支持 Redis 集群模式（即不支持分片）。

务必设置 Redis 参数 maxmemory-policy=noeviction，以避免队列任务被逐出缓存。

Kubernetes 中部署 Redis（Helm）

Bitnami 提供了 Redis 和 Valkey 的 Helm Chart。我们使用 Valkey 作为 Langfuse K8s 部署的依赖。详见 [Langfuse on Kubernetes (Helm)] 文档以获取完整部署指南。

在部署 ClickHouse Helm Chart 时，推荐使用如下 values.yaml 覆盖值来配置 Valkey：

valkey:deploy: truearchitecture: standaloneprimary:extraFlags:- "--maxmemory-policy noeviction" # 正确处理队列任务所必需auth:password: changeme

连接该 Redis 实例的环境变量示例：

REDIS_CONNECTION_STRING=redis://default:changeme@<chart-name>-valkey-master:6379/0

Docker 单机部署

你也可以在单个 Docker 容器中运行 Redis，但由于没有冗余，不推荐用于生产环境。

启动命令如下：

docker run --name redis \-p 6379:6379 \redis --requirepass myredissecret --maxmemory-policy noeviction

对应的环境变量：

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_AUTH=myredissecret

资源建议（Sizing Recommendations）

Langfuse 主要使用 Redis 队列事件元数据，由 worker 进行处理。在大多数情况下，worker 能够及时处理队列，避免事件积压。建议 Redis 实例每分钟处理约 10 万事件时，分配约 1GB 内存。

Redis 权限设置

Redis 支持基于用户的访问控制列表（ACL），允许限制特定用户可访问的键和命令（参见 Redis ACL 文档）。Langfuse 要求提供的用户拥有当前数据库中所有键和命令的访问权限，即：

~* +@all

S3 / Blob 存储

Langfuse 使用 S3 或其他兼容 S3 协议的对象存储（以下简称 S3）来存储原始事件、多模态输入、批量导出文件及其他资源。此外，我们也专门支持 Azure Blob Storage 和 Google Cloud Storage。你可以使用 AWS、Cloudflare 等托管服务，也可以使用 MinIO 自行部署。我们使用该存储方案来提供高可扩展性和强一致性的读写能力，尤其适合大文件的持久存储。

配置说明

Langfuse 针对不同场景使用 S3，可以为每种用途单独配置存储桶。你可以为不同场景使用独立的 bucket，也可以通过路径前缀将它们存储在同一个 bucket 中。

强制配置项（用于事件上传）

以下环境变量为每个部署所必需，必须分别配置在 Langfuse Web 容器和 Worker 容器中：

环境变量	是否必需 / 默认值	描述
LANGFUSE_S3_EVENT_UPLOAD_BUCKET	必需	用于存储事件信息的 bucket 名称
LANGFUSE_S3_EVENT_UPLOAD_PREFIX	默认 ""	事件的子路径前缀，必须以 / 结尾
LANGFUSE_S3_EVENT_UPLOAD_REGION	可选	bucket 所在区域
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT	可选	上传事件所使用的 endpoint
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID	可选	bucket 的访问密钥（需有 List、Get、Put 权限）
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY	可选	bucket 的密钥
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE	可选	是否强制使用 path-style 请求（MinIO 需要此项）

可选配置项

Langfuse 还支持通过 S3 实现多模态追踪和批量导出，以下分别说明：

多模态追踪配置

用于上传媒体资源文件的配置项：

环境变量	默认值 / 是否必需	描述
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET	必需	用于上传媒体文件的 bucket
LANGFUSE_S3_MEDIA_UPLOAD_PREFIX	默认 ""	子路径前缀，需以 / 结尾
LANGFUSE_S3_MEDIA_UPLOAD_REGION	可选	bucket 区域
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT	可选	媒体上传 endpoint
LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID	可选	访问密钥（需有 List、Get、Put 权限）
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY	可选	访问密钥
LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE	可选	是否强制 path-style（MinIO 需要）
LANGFUSE_S3_MEDIA_MAX_CONTENT_LENGTH	默认 1_000_000_000	允许上传的最大文件大小（单位：字节，默认 1GB）
LANGFUSE_S3_MEDIA_DOWNLOAD_URL_EXPIRY_SECONDS	默认 3600	下载预签名链接的有效期（秒）

批量导出配置

Langfuse 支持通过 S3 批量导出表格数据（CSV 或 JSON）。中间结果将上传至 S3，并生成下载链接。

环境变量	默认值 / 是否必需	描述
LANGFUSE_S3_BATCH_EXPORT_ENABLED	默认 false	是否启用批量导出（必须设为 true 才生效）
LANGFUSE_S3_BATCH_EXPORT_BUCKET	必需	批量导出文件上传所用的 bucket
LANGFUSE_S3_BATCH_EXPORT_PREFIX	默认 ""	子路径前缀，需以 / 结尾
LANGFUSE_S3_BATCH_EXPORT_REGION	可选	bucket 区域
LANGFUSE_S3_BATCH_EXPORT_ENDPOINT	可选	endpoint
LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID	可选	访问密钥（需有 List、Get、Put 权限）
LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY	可选	访问密钥
LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE	可选	是否强制 path-style（MinIO 需要）
LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT	可选	用于生成预签名链接的外部 endpoint（用于保持流量在 VPC 内）
BATCH_EXPORT_PAGE_SIZE	默认 500	批量导出分页大小（防止内存压力）
BATCH_EXPORT_ROW_LIMIT	默认 1_500_000	单个导出任务的最大行数

部署方式示例

以事件上传为例，介绍常见部署方案：

Amazon S3（推荐）

Langfuse 默认使用 AWS SDK，支持 IAM 角色或 Access Key 认证。

IAM 角色权限示例：

{"Version": "2012-10-17","Statement": [{"Action": ["s3:PutObject", "s3:ListBucket", "s3:GetObject"],"Effect": "Allow","Resource": ["arn:aws:s3:::<my-bucket-name>/*","arn:aws:s3:::<my-bucket-name>"]}]
}

启用数据保留功能时需增加：

• 权限：s3:DeleteObject

KMS 加密支持配置：

环境变量	描述
LANGFUSE_S3_EVENT_UPLOAD_SSE	服务器端加密算法（aws:kms 或 AES256）
LANGFUSE_S3_EVENT_UPLOAD_SSE_KMS_KEY_ID	使用的 KMS 密钥 ID
（媒体上传和导出也有类似变量）

KMS 权限：

{"Version": "2012-10-17","Statement": [{"Action": ["kms:GenerateDataKey", "kms:Decrypt"],"Effect": "Allow","Resource": "arn:aws:kms:region:account-id:key/key-id"}]
}

MinIO（本地开发或自托管）

docker run --name minio \-p 9000:9000 \-p 9001:9001 \-e MINIO_ROOT_USER=minio \-e MINIO_ROOT_PASSWORD=miniosecret \minio/minio server /data --console-address ":9001"

访问 http://localhost:9001 创建名为 langfuse 的 bucket。

环境变量示例：

LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse
LANGFUSE_S3_EVENT_UPLOAD_REGION=us-east-1
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=minio
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=miniosecret
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=http://minio:9000
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE=true
LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/

注意：默认数据是临时的，需配置持久卷或使用云服务保存数据。

Cloudflare R2

Cloudflare 提供兼容 S3 的 R2 存储。

环境变量示例：

LANGFUSE_S3_EVENT_UPLOAD_BUCKET=my-bucket-name
LANGFUSE_S3_EVENT_UPLOAD_REGION=auto
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=<access-key-id>
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=<secret-access-key>
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=https://${ACCOUNT_ID}.r2.cloudflarestorage.com

Azure Blob Storage

Azure 不兼容 S3 API，Langfuse 提供专用支持。

环境变量示例（使用 Azurite）：

LANGFUSE_USE_AZURE_BLOB=true
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=devstoreaccount1
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=<your-key>
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=http://localhost:10000/devstoreaccount1

Google Cloud Storage

原生集成（推荐）

LANGFUSE_USE_GOOGLE_CLOUD_STORAGE=true
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse
LANGFUSE_GOOGLE_CLOUD_STORAGE_CREDENTIALS=<json 或文件路径>
LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/

兼容模式（HMAC）

LANGFUSE_S3_EVENT_UPLOAD_BUCKET=my-bucket-name
LANGFUSE_S3_EVENT_UPLOAD_REGION=auto
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=<HMAC Access Key>
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=<HMAC Secret Key>
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=https://storage.googleapis.com
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE=true
LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/

Postgres 数据库

Langfuse 需要一个持久化的 Postgres 数据库来存储其状态。你可以使用 AWS、Azure 或 GCP 上的托管服务，或自行部署数据库。

Langfuse 支持 Postgres 12 及以上版本，并使用所选数据库中的 public 模式（schema）。

使用场景

Postgres 用于存储所有事务性数据，包括：

• 用户（Users）
• 组织（Organizations）
• 项目（Projects）
• 数据集（Datasets）
• 加密的 API 密钥（Encrypted API keys）
• 设置（Settings）
• 配置（Configuration）
• 时区（Timezones）

Langfuse 要求其基础设施组件默认使用 UTC 时区。特别是 Postgres 和 ClickHouse 中覆盖 UTC 默认设置的行为不受支持，可能会导致意外行为。

LangFuse: LangSmith平替

官方网站：https://langfuse.com/
项目地址：https://github.com/langfuse

由于LangFuse本地化部署还是需要一定的配置，因此个人用户可以使用LangFuse的云平台开发，如果电脑实在性能差，则minio，redis，pgsql，clickhouse都可以使用相应供应商的云平台。

我简称以上为拼好Fuse，话不多说直接开始！

先注册，登录，官网地址在上面：

创建组织和Project：

生成私钥和公钥（一定要复制并记录下这个私钥和公钥，关闭这个窗口后，私钥就再也看不到了。）：

本地安装 langfuse

pip install --upgrade langfuse

LangChain集成：

from langfuse import Langfuse
from langfuse.langchain import CallbackHandlerlangfuse = Langfuse(public_key="",secret_key="",host=""
)langfuse_handler = CallbackHandler()# <Your Langchain code here># Add handler to run/invoke/call/chat
chain.invoke({"input": "<user_input>"}, config={"callbacks": [langfuse_handler]})

运行之后看下LangFuse平台，应该能看到你的项目和调用了。