# https://github.com/langfuse/langfuse 项目说明书
生成时间：2026-05-14 08:22:55 UTC
## 目录
- [项目介绍](#p-intro)
- [仓库结构](#p-structure)
- [系统架构](#p-architecture)
- [数据库设计](#p-database)
- [追踪系统](#p-tracing)
- [提示词管理](#p-prompts)
- [评估系统](#p-evaluations)
- [数据集管理](#p-datasets)
- [队列系统](#p-queues)
- [API 系统](#p-api)
## 项目介绍
### 相关页面
相关主题：[仓库结构](#p-structure), [系统架构](#p-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/langfuse/langfuse/blob/main/package.json)
- [web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)
- [web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)
- [web/src/features/entitlements/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/entitlements/README.md)
- [web/src/features/feature-flags/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/feature-flags/README.md)
- [web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)
- [web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)
- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)
# 项目介绍
Langfuse 是一个开源的 LLM（大型语言模型）可观测性和评估平台，专注于帮助开发团队追踪、监控和优化其 AI 应用的性能与质量。本文档将从项目架构、核心功能模块和技术实现等方面对 Langfuse 进行全面介绍。
## 项目概述
Langfuse 项目采用 **Monorepo**（单体仓库）架构，使用 pnpm 作为包管理器进行多包管理。项目的核心依赖和配置信息集中在根目录的 `package.json` 中定义，通过 pnpm workspace 机制管理多个子项目。资料来源：[package.json:1-50]()
### 技术栈概览
Langfuse 的技术栈涵盖前后端多个层面：
| 层级 | 技术选型 | 说明 |
|------|----------|------|
| 前端框架 | Next.js / React | Web 应用核心框架 |
| 包管理器 | pnpm 10.33.0 | 项目依赖管理 |
| 编程语言 | TypeScript | 全栈 TypeScript 开发 |
| 后端服务 | Python/Worker | 数据处理和队列管理 |
| 数据存储 | PostgreSQL, ClickHouse, Redis, S3 | 多样化数据存储方案 |
| 状态管理 | React Context + Hooks | 前端状态管理 |
| UI 组件 | Tailwind CSS + CVA | 样式和组件变体 |
```mermaid
graph TD
A[Langfuse Monorepo] --> B[web/ - 前端应用]
A --> C[worker/ - 后端 Worker]
A --> D[packages/shared/ - 共享包]
B --> E[React Components]
B --> F[Feature Modules]
C --> G[Queue Processors]
C --> H[Data Ingestion]
D --> I[Shared Types]
D --> J[Validation Schemas]
```
## 架构设计
### Monorepo 结构
Langfuse 采用 pnpm workspace 实现的 Monorepo 架构，主要包含以下几个核心包：
- **web**: 前端 Next.js 应用，包含 UI 组件系统和业务功能模块
- **worker**: 后端 Worker 服务，处理数据摄取、队列管理和事件处理
- **packages/shared**: 前后端共享的类型定义、验证模式和业务接口
资料来源：[package.json:20-40]()
### 前端架构分层
前端代码遵循清晰的分层设计原则：
```mermaid
graph TB
subgraph web/src/components
A[layouts/ - 页面布局组件]
B[design-system/ - 基础设计系统]
C[ui/ - 通用 UI 组件]
D[table/ - 表格组件]
end
subgraph web/src/features
E[entitlements/ - 权限系统]
F[feature-flags/ - 功能开关]
G[mcp/ - MCP 服务器]
H[score-analytics/ - 分数分析]
I[filters/ - 过滤器系统]
J[comments/ - 评论功能]
end
A --> B
B --> C
D --> C
E --> F
```
#### 布局系统 (layouts)
`Page` 组件是所有页面的标准包装器，确保应用具有一致的布局、粘性头部和适当的滚动行为。所有页面必须包装在 `` 组件内，不能直接使用 `` 元素。
关键特性：
- 封装的粘性头部 - 防止布局不一致
- 滚动管理 - 支持 "content-scroll" 和 "page-scroll" 两种模式
- 标准化的内边距和布局
- 面包屑导航支持
- 自定义头部操作区域
资料来源：[web/src/components/layouts/README.md:1-30]()
#### 设计系统 (design-system)
设计系统文件夹包含**可复用的、原始的、展示性质的 UI 组件**。设计原则如下：
| 原则 | 说明 |
|------|------|
| 纯展示性 | 不包含业务逻辑 |
| 显式类型 | 使用严格的 TypeScript 类型定义 |
| 一致性优先 | 优先考虑一致性而非灵活性 |
| Props 优先 | 使用 Props 而非 React Context |
**组件规范**：
- 一个组件一个文件
- 使用 CVA (Class Variance Authority) 管理变体
- 使用显式枚举定义尺寸和变体类型
- 布尔属性使用 `is`/`should` 前缀命名
资料来源：[web/src/components/design-system/README.md:1-50]()
## 核心功能模块
### 权限系统 (entitlements)
Entitlements 系统用于控制功能的可用性，基于组织 (organization) 级别进行管理。
核心概念：
- **Plan（套餐）**: 功能层级的划分，如 `oss`、`cloud:pro`、`self-hosted:enterprise`
- **Entitlement（权限）**: 用户可用的功能特性，如 `playground`
- **EntitlementLimit（权限限制）**: 资源数量限制，如 `annotation-queue-count`
权限使用方式：
| 使用场景 | 实现方式 |
|----------|----------|
| 客户端 | React Hooks (`hooks.ts`) |
| 服务端 | `hasEntitlement.ts` / `hasOrganizationEntitlement` |
资料来源：[web/src/features/entitlements/README.md:1-35]()
### 功能开关 (feature-flags)
Feature Flags 允许在运行时动态控制功能启用状态。
功能开关启用条件（满足任一即可）：
1. 用户在 `user.feature_flags` 中包含该标志
2. 环境变量 `LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES` 被设置
3. 用户具有管理员权限 (`user.admin === true`)
```typescript
const isFeatureEnabled = useIsFeatureEnabled("feature-flag-name");
```
资料来源：[web/src/features/feature-flags/README.md:1-15]()
### MCP 服务器 (mcp)
Langfuse MCP 服务器提供了 6 个 Prompt 管理工具，采用**无状态按请求架构**：
| 工具名称 | 功能描述 |
|----------|----------|
| `getPrompt` | 获取完全解析的 Prompt（包含依赖替换） |
| `getPromptUnresolved` | 获取原始 Prompt（保留依赖标签） |
| `listPrompts` | 列出项目中所有 Prompt |
| `createTextPrompt` | 创建新的文本 Prompt 版本 |
| `createChatPrompt` | 创建新的聊天 Prompt 版本 |
| `updatePromptLabels` | 更新 Prompt 标签 |
**架构特点**：
- 每个 MCP 请求创建新的服务器实例
- 认证上下文通过闭包捕获
- 请求完成后服务器被丢弃
- 请求间无状态共享
```mermaid
graph LR
A[MCP Client] -->|Request| B[New Server Instance]
B --> C[Handler with Auth Closure]
C --> D[Process Request]
D --> E[Return Response]
E --> F[Discard Server]
```
资料来源：[web/src/features/mcp/README.md:1-80]()
### 分数分析 (score-analytics)
分数分析模块提供数据分析和可视化功能。
#### 关键组件
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| `ScoreAnalyticsProvider` | ScoreAnalyticsProvider.tsx | 上下文提供者，管理数据状态 |
| `useScoreAnalyticsQuery` | useScoreAnalyticsQuery.ts | 数据获取和转换 |
#### 数据转换管道
```
API Response → Extract Categories → Fill Distribution Bins →
Generate Bin Labels → Transform Heatmap → Calculate Mode Metrics →
Fill Time Series Gaps → Namespace Categorical → Final Output
```
#### 统计分析工具
`s statistics-utils.ts` 提供了多种统计分析函数：
| 函数 | 功能 | 输出 |
|------|------|------|
| `interpretAgreement` | 解释一致性指标 | Strength + Color + Description |
| `interpretMAE` | 解释平均绝对误差 | 相对误差分析 |
资料来源：[web/src/features/score-analytics/README.md:1-60]()
### 分数接口系统 (scores/interfaces)
分数接口定义了完整的类型系统，支持多版本 API。
#### API 版本支持
| API 版本 | traceId 要求 | 支持范围 |
|----------|-------------|----------|
| v1 | 必需 | 仅 Trace 级别分数 |
| v2 | 可选 | Trace + Session |
#### 接口目录结构
```
interfaces/
├── api/
│ ├── v1/ # 遗留 API 类型
│ ├── v2/ # 当前 API 类型
│ └── shared.ts # 共享模式
├── application/ # 应用层验证
├── ingestion/ # 摄取类型
└── ui/ # UI 专用类型
```
资料来源：[packages/shared/src/features/scores/interfaces/README.md:1-40]()
### 过滤器系统 (filters)
过滤器系统提供灵活的查询条件编码和解码功能。
**支持的过滤类型**：
| 类型 | 编码方式 | 说明 |
|------|----------|------|
| `datetime` | Date 对象 | 时间范围过滤 |
| `number` | Number | 数值比较 |
| `stringOptions` | 管道分隔数组 | 字符串选项 |
| `arrayOptions` | 数组 | 数组匹配 |
| `boolean` | true/false | 布尔过滤 |
| `categoryOptions` | 分类选项 | 分类过滤 |
| `positionInTrace` | 位置索引 | Trace 内位置 |
资料来源：[web/src/features/filters/lib/filter-query-encoding.ts:1-50]()
### 表格 peek 功能 (table/peek)
PeekTable 系统允许在侧边栏中预览和查看表格数据，与主表格保持状态同步。
**关键 Hook**：
| Hook | 用途 |
|------|------|
| `usePeekTableState` | 管理 peek 上下文状态 |
| `useSidebarFilterState` | 过滤器状态管理 |
| `useOrderByState` | 排序状态管理 |
**状态位置优先级**：
1. Peek Context（peek 上下文）
2. URL & Session Storage（URL 和会话存储）
资料来源：[web/src/components/table/peek/README.md:1-50]()
### 高级 JSON 查看器 (ui/AdvancedJsonViewer)
用于可视化大型 JSON 数据的组件，具备以下能力：
| 特性 | 说明 |
|------|------|
| 虚拟化渲染 | 使用 TanStack Virtual 处理大数据集 |
| 迭代遍历 | 使用显式栈避免递归栈溢出 |
| 客户端搜索 | 内存内匹配计算 |
| 调试模式 | 通过 localStorage 启用详细日志 |
**算法特点**：
- 所有树操作使用**显式基于栈的迭代**而非递归
- 支持深度 1000+ 的树结构安全遍历
- 二进制搜索优化 `getNodeByIndex` 性能
资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md:1-80]()
### 评论提及功能 (comments/mentionParser)
支持用户提及功能的解析和处理。
**提及格式**：`@[DisplayName](user:userId)`
**核心函数**：
| 函数 | 作用 |
|------|------|
| `extractUniqueMentionedUserIds` | 从文本中提取所有被提及的用户 ID |
| `sanitizeMentions` | 清理和验证提及内容 |
| `MENTION_USER_PREFIX` | 常量 `"user:"` |
资料来源：[web/src/features/comments/lib/mentionParser.clienttest.ts:1-30]()
## 后端 Worker 系统
### 事件重放脚本 (replayIngestionEventsV2)
用于将历史事件重新摄取到系统的工具脚本。
**主要功能**：
- 从 S3 读取历史事件
- 通过 HTTP POST 发送到 Langfuse Host
- 支持检查点恢复
- 内置速率限制和重试机制
**事件键格式**：
| 类型 | 格式 | 目标队列 |
|------|------|----------|
| 标准键 | `{projectId}/{type}/{eventBodyId}/{eventId}.json` | IngestionSecondaryQueue |
| OTEL 键 | `otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json` | OtelIngestionQueue |
**状态码处理**：
| 状态码 | 含义 | 处理方式 |
|--------|------|----------|
| 200 | 批次接受 | 检查 skipped/errors |
| 401 | 认证失败 | 停止处理 |
| 400 | 请求格式错误 | 跳过并记录 |
| 429 | 速率限制 | 指数退避重试 |
**v1 vs v2 差异**：
| 特性 | v1 | v2 |
|------|----|----|
| 基础设施访问 | Redis, ClickHouse, PostgreSQL, S3 | 仅 Langfuse Host URL |
| 事件传递 | 直接 BullMQ addBulk | HTTP POST 到 Admin API |
| 恢复支持 | 手动分割文件 | 内置检查点/恢复 |
| 速率限制 | 无 | 客户端+服务端双重限制 |
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md:1-120]()
### 队列填充脚本 (refillQueueEvent)
用于从本地机器回填队列事件的实用工具脚本。
**使用流程**：
1. 创建 `./worker/events.jsonl` 文件
2. 配置 `.env` 环境变量
3. 确保 Redis 连接可达
4. 执行 `pnpm run --filter=worker refill-queue-event`
**环境变量要求**：
```bash
REDIS_CONNECTION_STRING=redis://:myredissecret@127.0.0.1:6379
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse
CLICKHOUSE_URL=http://localhost:8123
CLICKHOUSE_USER=clickhouse
CLICKHOUSE_PASSWORD=clickhouse
```
资料来源：[worker/src/scripts/refillQueueEvent/README.md:1-50]()
## 依赖管理
### pnpm Overrides
项目使用 pnpm overrides 强制管理依赖版本：
| 依赖包 | 锁定版本 | 备注 |
|--------|----------|------|
| zod | 4.3.6 | 数据验证库 |
| nanoid | ^3.3.8 | ID 生成 |
| katex | ^0.16.21 | 数学渲染 |
| rollup | ^4.22.4 | 打包工具 |
| @types/react-dom | 19.2.3 | React 类型 |
| qs | 6.14.1 | 查询字符串解析 |
| glob | ^10.5.0 | 文件匹配 |
资料来源：[package.json:55-75]()
## 总结
Langfuse 是一个功能完备的 LLM 可观测性平台，其架构设计体现了以下特点：
1. **Monorepo 组织**：通过 pnpm workspace 高效管理多个相关包
2. **清晰的分层**：前端组件与业务逻辑分离，设计系统独立维护
3. **多版本 API 支持**：v1/v2 API 并存，保证向后兼容
4. **灵活的扩展机制**：Feature Flags 和 Entitlements 支持动态功能控制
5. **完善的工具链**：事件重放、队列填充等运维工具完备
该平台适用于需要追踪 AI 应用行为、评估模型性能、管理 Prompt 版本的开发团队。
---
## 仓库结构
### 相关页面
相关主题：[项目介绍](#p-intro), [系统架构](#p-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)
- [web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)
- [web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)
- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)
- [worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)
- [package.json](https://github.com/langfuse/langfuse/blob/main/package.json)
- [web/src/components/table/peek/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/table/peek/README.md)
- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
- [web/src/features/entitlements/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/entitlements/README.md)
- [web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)
- [web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)
# 仓库结构
## 概述
Langfuse 是一个开源的 LLMOps 平台，采用 Monorepo（单体仓库）架构进行项目管理。整个仓库包含多个子项目，通过 pnpm workspace 进行统一管理和协调。资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)
该架构的核心设计目标是：
- **代码共享**：在多个包之间共享类型定义、工具函数和业务逻辑
- **统一版本管理**：所有子项目保持一致的依赖版本
- **简化开发流程**：一次安装即可配置好所有开发环境
Langfuse 的主要子系统包括：
| 子系统 | 描述 |
|--------|------|
| **web** | Next.js 前端应用，提供用户界面 |
| **worker** | 后台任务处理器，处理数据摄入和异步任务 |
| **packages/shared** | 共享包，包含类型定义和跨模块复用代码 |
资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)
---
## 项目架构总览
Langfuse 采用分层架构，各层之间职责清晰、边界明确：
```mermaid
graph TD
A[用户界面层
web/src] --> B[业务功能层
web/src/features]
B --> C[共享组件层
web/src/components]
C --> D[设计系统层
design-system]
A --> E[packages/shared]
F[后台处理层
worker/src] --> E
G[脚本工具层
worker/src/scripts] --> F
```
资料来源：[web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)
---
## Web 前端模块
Web 模块是 Langfuse 的用户界面层，基于 Next.js 框架构建。它采用模块化组织，将功能代码按领域进行划分。
### 目录结构概览
```
web/src/
├── components/ # UI 组件库
│ ├── layouts/ # 页面布局组件
│ ├── ui/ # 基础 UI 组件
│ ├── table/ # 表格相关组件
│ └── design-system/ # 设计系统
├── features/ # 功能模块
└── ...
```
资料来源：[web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)
### 页面布局组件
`Page` 组件是所有页面的标准包装器，确保应用具有一致的布局、粘性头部和正确的滚动行为。
```tsx
import Page from "@/src/components/layouts/Page";
export default function MyPage() {
return (
Save,
}}
>
My page content here...
);
}
```
资料来源：[web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)
**重要约束**：
- ⚠️ 每个页面都必须包装在 `` 内，切勿直接使用 ``
- 当内容无法良好适应页面宽度时，应使用 `ContainerPage` 组件
### 设计系统
设计系统位于 `web/src/components/design-system/`，包含可复用的基础 UI 组件。
#### 组件设计原则
| 原则 | 说明 |
|------|------|
| 仅展示性质 | 不包含业务逻辑 |
| 显式类型 API | 使用严格的 TypeScript 类型定义 |
| 一致性优先 | 优先考虑一致性而非灵活性 |
| Props 优于 Context | 避免使用 React Context |
资料来源：[web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)
#### 目录结构
```
design-system/
Button/
Button.tsx
Button.stories.tsx
```
#### 样式与变体规范
- ❌ 禁止使用 `className` 或 `style` props
- ❌ 禁止使用任意值（如 `#fff`、`12px`）
- ✅ 使用显式枚举
```ts
size: "sm" | "md" | "lg";
variant: "primary" | "secondary";
```
#### Props 命名约定
| 类型 | 命名方式 |
|------|----------|
| 布尔属性 | `isLoading`、`shouldTruncate` |
| 互斥属性 | 使用正向命名：`suffix={null}` |
资料来源：[web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)
### 高级 JSON 查看器
位于 `web/src/components/ui/AdvancedJsonViewer/`，提供虚拟化的大 JSON 数据展示能力。
#### 已知限制
| 限制 | 说明 |
|------|------|
| 无水平虚拟化 | 换行模式下会完全渲染所有宽行 |
| 仅客户端搜索 | 所有匹配在内存中计算 |
| 内存约束 | 100万+ 节点可能导致问题 |
| 只读查看器 | 不支持内联编辑 |
资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)
#### 算法设计
所有树操作使用显式基于栈的迭代而非递归：
```typescript
// ❌ 递归（深度 1000+ 可能栈溢出）
function traverse(node: TreeNode) {
process(node);
node.children.forEach((child) => traverse(child));
}
// ✅ 迭代（任意深度都安全）
function traverse(rootNode: TreeNode) {
const stack = [rootNode];
while (stack.length > 0) {
const node = stack.pop()!;
process(node);
node.children.forEach((child) => stack.push(child));
}
}
```
资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)
### 表格 Peek 功能
`peek` 模块位于 `web/src/components/table/peek/`，支持在侧边栏中预览表格数据。
#### Peek 感知状态管理
| Hook | 用途 |
|------|------|
| `useTextSearch` | 文本搜索 |
| `useSidebarFilterState` | 过滤器状态 |
| `useOrderByState` | 排序状态 |
资料来源：[web/src/components/table/peek/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/table/peek/README.md)
---
## 功能模块（Features）
`web/src/features/` 目录包含各业务领域的功能实现。
### Public API 模块
Public API 提供了外部访问 Langfuse 功能的接口。
#### 新增 API 路由的流程
| 步骤 | 操作 |
|------|------|
| 1 | 使用 `withMiddleware` 包装 |
| 2 | 使用 `createAuthedAPIRoute` 创建类型安全的路由 |
| 3 | 在 `/features/public-api/types` 添加 Zod 类型 |
| 4 | 使用 `strict()` 定义响应对象 |
| 5 | 抛出 `shared/src/errors` 中定义的错误 |
| 6 | 使用 `makeZodVerifiedAPICall` 进行测试 |
资料来源：[web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)
### MCP 服务器模块
MCP（Model Context Protocol）服务器位于 `web/src/features/mcp/`，提供提示词管理功能。
#### 架构特点
| 特点 | 说明 |
|------|------|
| 无状态设计 | 每个请求创建新的服务器实例 |
| 闭包捕获上下文 | 认证上下文在处理函数闭包中捕获 |
| 无会话存储 | 请求完成后服务器被丢弃 |
资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)
#### 可用工具
| 工具 | 功能 |
|------|------|
| `getPrompt` | 获取已解析的提示词（含依赖替换） |
| `getPromptUnresolved` | 获取未解析的提示词（保留原始标签） |
| `listPrompts` | 列出所有提示词（支持过滤和分页） |
| `createTextPrompt` | 创建文本提示词版本 |
| `createChatPrompt` | 创建聊天提示词版本 |
| `updatePromptLabels` | 更新提示词标签 |
资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)
#### 提示词解析示例
```
输入: "You are helpful. @@@langfusePrompt:name=base-rules|label=production@@@"
输出: "You are helpful. Always be kind and respectful."
```
### Entitlements 模块
位于 `web/src/features/entitlements/`，用于控制功能可用性。
#### 核心概念
| 概念 | 说明 |
|------|------|
| **Plan** | 功能层级，如 `oss`、`cloud:pro`、`self-hosted:enterprise` |
| **Entitlement** | 可用功能，如 `playground` |
| **EntitlementLimit** | 资源限制，如 `annotation-queue-count` |
资料来源：[web/src/features/entitlements/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/entitlements/README.md)
#### Plan 的管理方式
| 环境 | 管理方式 |
|------|----------|
| Cloud | 通过 NextAuth 添加到 JWT 的 organization 对象 |
| Self-hosted | 通过 NextAuth 添加到 JWT 的 `environment.selfHostedInstancePlan` |
---
## 共享包（packages/shared）
`packages/shared` 包含跨模块复用的类型定义和工具函数。
### Score 接口
位于 `packages/shared/src/features/scores/interfaces/`，定义分数相关的类型和验证逻辑。
#### 目录结构
```
interfaces/
├── api/ # API 相关类型
│ ├── v1/ # 遗留 API 类型（仅 trace）
│ ├── v2/ # 当前 API 类型（支持 trace、session）
│ └── shared.ts # 通用类型
├── application/ # 应用层验证
├── ingestion/ # 数据摄入类型
└── ui/ # UI 组件类型
```
资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
#### API 版本差异
| 操作 | V1 API | V2 API |
|------|--------|--------|
| GET | 需要 `traceId`，仅支持 trace 级分数 | `traceId` 可选，支持 `sessionId` |
| POST/DELETE | 支持所有类型 | 支持所有类型 |
资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
---
## Worker 后台处理模块
`worker` 模块负责处理后台任务，包括数据摄入和异步任务执行。
### 脚本工具
位于 `worker/src/scripts/`，提供数据处理和队列管理工具。
#### Replay Ingestion Events V2
用于重放 S3 中的摄入事件到 Langfuse。
**事件转换规则**：
| 事件类型 | 键格式 | 目标队列 |
|----------|--------|----------|
| 标准事件 | `{projectId}/{type}/{eventBodyId}/{eventId}.json` | IngestionSecondaryQueue |
| OTEL 事件 | `otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json` | OtelIngestionQueue |
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)
#### Refill Queue Event
用于从本地机器回填队列事件。
**环境要求**：
| 变量 | 说明 |
|------|------|
| `REDIS_CONNECTION_STRING` | Redis 连接字符串 |
| `CLICKHOUSE_URL` | ClickHouse 服务器地址 |
| `LANGFUSE_S3_EVENT_UPLOAD_BUCKET` | S3 存储桶名称 |
资料来源：[worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)
---
## 依赖管理
### pnpm Workspace 配置
Langfuse 使用 pnpm workspace 管理多包项目，通过 `package.json` 中的 `pnpm` 配置进行全局依赖覆盖。
```json
{
"pnpm": {
"overrides": {
"zod": "4.3.6",
"nanoid": "^3.3.8",
"katex": "^0.16.21",
"tar-fs": "^2.1.2",
"rollup@^4.0.0": "^4.22.4"
}
}
}
```
资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)
### 包管理器版本
Langfuse 使用 `pnpm@10.33.0` 作为包管理器。
资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)
---
## 技术栈总结
```mermaid
graph LR
subgraph "前端层"
A[Next.js]
B[React]
C[Tailwind CSS]
end
subgraph "后端层"
D[Worker]
E[BullMQ]
F[Redis]
end
subgraph "数据层"
G[ClickHouse]
H[S3 Storage]
I[PostgreSQL]
end
A --> G
A --> I
D --> E
E --> F
D --> G
D --> H
```
---
## 开发指南
### 添加新功能模块
1. 在 `web/src/features/` 下创建新模块目录
2. 在 `web/src/components/design-system/` 中添设计系统组件
3. 在 `packages/shared` 中添加共享类型定义
4. 更新 API 路由时使用标准流程
资料来源：[web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)
### 运行测试
```bash
# 运行前端测试
pnpm --filter=web run test-client --testPathPattern="AdvancedJsonViewer"
# 运行工作线程脚本
pnpm run --filter=worker refill-queue-event
```
资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)、[worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)
---
## 系统架构
### 相关页面
相关主题：[数据库设计](#p-database), [队列系统](#p-queues), [仓库结构](#p-structure)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/shared/src/server/redis/redis.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/redis.ts)
- [packages/shared/src/server/clickhouse/client.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/clickhouse/client.ts)
- [packages/shared/src/db.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/db.ts)
- [worker/src/app.ts](https://github.com/langfuse/langfuse/blob/main/worker/src/app.ts)
- [web/next.config.mjs](https://github.com/langfuse/langfuse/blob/main/web/next.config.mjs)
# 系统架构
## 概述
Langfuse 是一个开源的 LLM 工程平台，采用分布式微服务架构设计。系统由多个核心组件构成，包括 Web 前端服务、Worker 后台处理服务、数据存储层和缓存层。这种架构设计实现了前端展示与后端处理的分离，保证了系统的高可用性和可扩展性。
Langfuse 的技术栈涵盖了现代 Web 开发的多个层面：使用 Next.js 构建前端应用、使用 BullMQ 与 Redis 实现异步任务队列、使用 PostgreSQL 存储核心业务数据、使用 ClickHouse 处理分析查询、使用 S3 兼容存储管理事件文件。
## 核心架构组件
### 整体架构图
```mermaid
graph TB
subgraph Client["客户端层"]
Web[Web 前端
Next.js]
end
subgraph API["API 层"]
TRPC[tRPC API]
end
subgraph Worker["Worker 层"]
Queue[BullMQ 队列]
Worker[Worker 进程]
end
subgraph Storage["存储层"]
Redis[(Redis
队列/缓存)]
Postgres[(PostgreSQL
核心数据)]
ClickHouse[(ClickHouse
分析数据)]
S3[(S3 存储
事件文件)]
end
Web --> TRPC
TRPC --> Postgres
TRPC --> Redis
TRPC --> ClickHouse
TRPC --> S3
Queue --> Redis
Worker --> Queue
Worker --> Postgres
Worker --> ClickHouse
Worker --> Redis
Worker --> S3
```
### 技术栈概览
| 组件 | 技术选型 | 用途 |
|------|----------|------|
| 前端框架 | Next.js | 用户界面和服务端渲染 |
| API 层 | tRPC | 类型安全的 API 调用 |
| 后台任务 | BullMQ + Worker | 异步任务处理 |
| 主数据库 | PostgreSQL | 业务数据持久化 |
| 分析数据库 | ClickHouse | OLAP 查询和分析 |
| 缓存/队列 | Redis | 缓存、限流、队列 |
| 对象存储 | S3 兼容 | 事件文件存储 |
## Web 前端服务
### Next.js 应用架构
Web 前端基于 Next.js 框架构建，采用 App Router 架构进行路由管理。前端服务负责用户交互界面、数据展示和 API 调用。
Web 前端的源码位于 `web/` 目录，其核心配置文件包括 Next.js 配置和应用程序入口点。
```mermaid
graph LR
subgraph Web["Web 服务"]
Next[Next.js App]
Config[next.config.mjs]
Components[React 组件]
Features[Feature 模块]
end
subgraph API["后端通信"]
TRPC[tRPC Client]
HTTP[REST API]
end
Next --> Components
Next --> Features
Components --> TRPC
Features --> TRPC
TRPC --> HTTP
```
前端采用模块化设计，将功能划分为独立的 Feature 目录，例如：
- `features/prompts` - 提示词管理
- `features/score-analytics` - 评分分析
- `features/filters` - 过滤功能
- `features/mcp` - MCP 服务器集成
- `features/comments` - 评论功能
- `features/entitlements` - 权限控制
## Worker 后台服务
### Worker 应用架构
Worker 服务是 Langfuse 的后台任务处理核心，负责处理异步任务，包括数据摄入、队列管理和事件处理。
Worker 的主入口文件位于 `worker/src/app.ts`，该文件初始化 Worker 应用并注册各种处理器。
```mermaid
graph TB
subgraph WorkerApp["Worker 应用"]
Init[应用初始化]
QueueProcessors[队列处理器]
Schedulers[定时任务]
end
subgraph Queues["队列系统"]
IngestionQueue[摄入队列]
OtelQueue[OTEL 队列]
SecondaryQueue[二级处理队列]
end
Init --> QueueProcessors
QueueProcessors --> IngestionQueue
QueueProcessors --> OtelQueue
QueueProcessors --> SecondaryQueue
```
### 队列系统
Langfuse 使用 BullMQ 实现任务队列，支持多种队列类型：
| 队列名称 | 用途 | 数据来源 |
|----------|------|----------|
| IngestionQueue | 事件摄入处理 | S3 文件 |
| OtelIngestionQueue | OpenTelemetry 数据摄入 | OTEL 格式文件 |
| IngestionSecondaryQueue | 二次处理队列 | 内部触发 |
| ScoreCalculationQueue | 评分计算 | 异步计算任务 |
### Worker 数据处理流程
```mermaid
graph TD
A[接收 HTTP 请求] --> B[验证请求参数]
B --> C{请求类型}
C -->|admin API| D[写入队列]
C -->|普通请求| E[直接处理]
D --> F[Worker 获取任务]
F --> G[读取 S3 文件]
G --> H[解析事件数据]
H --> I[数据转换]
I --> J[写入 PostgreSQL]
J --> K[写入 ClickHouse]
K --> L[任务完成]
E --> L
```
Worker 服务实现了无状态架构设计：每个 MCP 请求创建新的服务器实例，认证上下文通过闭包捕获，请求完成后服务器被丢弃，任务处理器之间无共享状态。
## 数据存储层
### PostgreSQL 数据库
PostgreSQL 作为 Langfuse 的主数据库，存储所有核心业务数据，包括用户信息、项目配置、提示词版本、追踪记录等。
数据库连接通过 `packages/shared/src/db.ts` 中的 Prisma Client 实现，该模块提供统一的数据库访问接口。
```mermaid
graph TB
subgraph Postgres[(PostgreSQL)]
Users[用户表]
Projects[项目表]
Prompts[提示词表]
Traces[追踪表]
Scores[评分表]
end
subgraph Tables["核心数据表"]
Organizations[组织表]
Members[成员表]
Datasets[数据集表]
end
```
### ClickHouse 分析数据库
ClickHouse 是 Langfuse 的分析查询引擎，专门用于处理大规模追踪数据的 OLAP 查询。分析功能包括评分趋势分析、热力图生成、时间序列聚合等。
ClickHouse 客户端配置位于 `packages/shared/src/server/clickhouse/client.ts`，该模块初始化 ClickHouse 连接并提供查询接口。
| 功能模块 | 数据表 | 用途 |
|----------|--------|------|
| score-analytics | 评分数据表 | 评分统计和分析 |
| traces | 追踪事件表 | 追踪数据分析 |
| observations | 观察数据表 | LLM 调用分析 |
### Redis 缓存与队列
Redis 在 Langfuse 架构中承担多重职责：作为任务队列的后端存储、实现 API 限流、提供数据缓存加速查询。
Redis 客户端配置位于 `packages/shared/src/server/redis/redis.ts`，该模块封装了 Redis 连接管理和常用操作。
```mermaid
graph LR
subgraph Redis[(Redis)]
Queues[BullMQ 队列]
Cache[数据缓存]
RateLimit[限流控制]
Locks[分布式锁]
end
subgraph CacheKeys["缓存键结构"]
PromptCache[prompt:{projectId}:{name}:{version}]
SessionCache[session:{sessionId}]
end
Redis --> Queues
Redis --> Cache
Redis --> RateLimit
Redis --> Locks
```
### S3 对象存储
S3 存储用于保存原始事件文件，包括追踪事件、OTEL 数据和大型 JSON 对象。Worker 服务从 S3 读取事件文件进行处理，处理后的结构化数据存入 PostgreSQL 和 ClickHouse。
事件文件存储路径遵循特定格式：`{projectId}/{type}/{eventBodyId}/{eventId}.json`，便于快速定位和检索。
## 服务间通信
### tRPC API 调用
Web 前端与后端服务通过 tRPC 进行类型安全的 API 通信。tRPC 提供了端到端的类型推断，减少了前后端接口不匹配的问题。
API 路由定义采用模块化结构，每个 Feature 拥有独立的 Router 文件，例如：
- `scoreAnalyticsRouter` - 评分分析 API
- `promptRouter` - 提示词管理 API
- `traceRouter` - 追踪数据 API
### 缓存策略
Langfuse 实现了多级缓存策略以提升系统性能：
1. **Redis 缓存层**：提示词内容缓存，避免重复查询数据库
2. **TTK 重置机制**：缓存条目被访问时自动重置 TTL
3. **写时失效**：数据更新时清除相关缓存条目
缓存键结构示例：`prompt:::`
```mermaid
graph TD
A[读取请求] --> B{检查 Redis 锁}
B -->|有锁| C[等待或降级]
B -->|无锁| D{检查缓存}
D -->|命中| E[返回缓存数据]
D -->|未命中| F[查询 PostgreSQL]
F --> G[写入 Redis]
G --> H[返回数据]
E --> I[重置 TTL]
```
## 权限与认证
### 组织级权限模型
Langfuse 采用组织级权限管理模型，权限通过 Plan 和 Entitlement 两层机制控制。
| 概念 | 定义 | 管理位置 |
|------|------|----------|
| Plan | 功能等级，如 oss、cloud:pro、self-hosted:enterprise | plans.ts |
| Entitlement | 具体功能，如 playground、annotation-queue-count | entitlements.ts |
| EntitlementLimit | 资源数量限制 | entitlements.ts |
Plan 信息通过以下方式获取：
- Cloud 版本：通过 NextAuth JWT 获取
- Self-hosted：通过环境变量或许可证密钥获取
### 权限检查流程
```mermaid
graph TB
A[请求进入] --> B{获取 Organization}
B --> C{检查 JWT 中的 Plan}
C -->|Cloud| D[使用 cloudConfig]
C -->|Self-hosted| E[检查许可证]
D --> F[加载 Entitlements]
E --> F
F --> G{验证功能权限}
G -->|通过| H[处理请求]
G -->|拒绝| I[返回 403]
```
## 部署架构
### 服务组件关系
```mermaid
graph TB
subgraph Deployment["部署拓扑"]
Web[Web 服务
Next.js]
API[API 服务]
Worker1[Worker 实例 1]
Worker2[Worker 实例 2]
WorkerN[Worker 实例 N]
end
subgraph Shared["共享服务"]
Redis[(Redis Cluster)]
Postgres[(PostgreSQL)]
ClickHouse[(ClickHouse)]
S3[(S3 兼容存储)]
end
Web --> API
API --> Redis
API --> Postgres
API --> ClickHouse
API --> S3
Worker1 --> Redis
Worker2 --> Redis
WorkerN --> Redis
Worker1 --> Postgres
Worker2 --> Postgres
WorkerN --> Postgres
Worker1 --> ClickHouse
Worker2 --> ClickHouse
Worker1 --> S3
Worker2 --> S3
```
### 环境配置
主要环境变量配置项：
| 变量名 | 用途 | 示例值 |
|--------|------|--------|
| DATABASE_URL | PostgreSQL 连接 | postgresql://user:pass@host:5432/db |
| REDIS_CONNECTION_STRING | Redis 连接 | redis://:secret@host:6379 |
| CLICKHOUSE_URL | ClickHouse 连接 | http://localhost:8123 |
| LANGFUSE_S3_EVENT_UPLOAD_BUCKET | S3 存储桶 | langfuse-events |
## 源码文件引用
本文档基于以下核心源码文件编写：
- `packages/shared/src/server/redis/redis.ts` - Redis 客户端封装
- `packages/shared/src/server/clickhouse/client.ts` - ClickHouse 连接配置
- `packages/shared/src/db.ts` - Prisma 数据库客户端
- `worker/src/app.ts` - Worker 应用入口
- `web/next.config.mjs` - Next.js 应用配置
---
## 数据库设计
### 相关页面
相关主题：[系统架构](#p-architecture), [追踪系统](#p-tracing)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/shared/prisma/schema.prisma](https://github.com/langfuse/langfuse/blob/main/packages/shared/prisma/schema.prisma)
- [packages/shared/clickhouse/migrations/clustered](https://github.com/langfuse/langfuse/blob/main/packages/shared/clickhouse/migrations/clustered)
- [packages/shared/src/server/repositories](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/repositories)
- [packages/shared/src/tableDefinitions](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/tableDefinitions)
- [worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)
# 数据库设计
## 概述
Langfuse 采用多数据库架构，针对不同的数据访问模式选择最适合的存储方案。系统主要使用三种数据存储技术：**PostgreSQL** 作为主关系型数据库，**ClickHouse** 用于事件分析和时序数据，**Redis** 用于缓存和消息队列。这种混合架构平衡了事务一致性、查询性能和实时处理能力。
资料来源：[packages/shared/prisma/schema.prisma]()
## 架构概览
```mermaid
graph TB
subgraph 客户端层
A[Langfuse SDK] --> B[Ingestion API]
C[Web UI] --> D[Management API]
end
subgraph 数据处理层
B --> E[BullMQ Queue]
E --> F[Worker Process]
end
subgraph 存储层
F --> G[(PostgreSQL)]
F --> H[(ClickHouse)]
F --> I[(Redis)]
D --> G
D --> H
end
subgraph 查询层
G --> J[Repository Pattern]
H --> K[ClickHouse Queries]
I --> L[Cache Layer]
end
```
Langfuse 的数据流向遵循以下原则：所有写入操作通过消息队列异步处理，确保高并发场景下的稳定性；读取操作根据数据类型选择最优存储引擎。`Observation` 和 `Trace` 等核心实体同时存在于 PostgreSQL 和 ClickHouse 中，前者保证关系完整性，后者支持复杂分析查询。
资料来源：[packages/shared/src/server/repositories]()
## PostgreSQL 核心表设计
### 实体关系模型
PostgreSQL 使用 Prisma ORM 进行模式管理，所有表设计遵循标准关系型数据库规范。核心实体包括组织、项目、用户、追踪、观察、提示词和数据集。
```mermaid
erDiagram
Organization ||--o{ Project : contains
Project ||--o{ ApiKey : has
Project ||--o{ Trace : contains
Project ||--o{ Dataset : contains
Project ||--o{ Prompt : contains
Trace ||--o{ Observation : contains
Trace ||--o{ Score : has
Observation ||--o{ Score : has
Dataset ||--o{ DatasetItem : contains
Dataset ||--o{ DatasetRun : has
User ||--o{ Membership : belongs_to
Organization ||--o{ Membership : has
```
### 主要数据表
| 表名 | 描述 | 关联 |
|------|------|------|
| `Organization` | 组织租户 | 顶层实体 |
| `Project` | 项目空间 | 属于组织 |
| `User` | 用户账户 | 通过Membership关联 |
| `Membership` | 组织成员关系 | User-Organization多对多 |
| `ApiKey` | API密钥 | 属于项目 |
| `Trace` | 追踪记录 | 属于项目 |
| `Observation` | 观察单元 | 属于追踪 |
| `Score` | 评分数据 | 可关联追踪或观察 |
| `Prompt` | 提示词模板 | 属于项目 |
| `Dataset` | 数据集 | 属于项目 |
| `DatasetItem` | 数据集项 | 属于数据集 |
| `DatasetRun` | 数据集运行 | 属于数据集 |
资料来源：[packages/shared/prisma/schema.prisma]()
### Trace 表结构
`Trace` 表是 Langfuse 数据模型的核心，用于记录完整的 LLM 调用会话：
```prisma
model Trace {
id String @id @default(cuid())
name String?
userId String?
projectId String
metadata Json?
release String?
version String?
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
observations Observation[]
scores Score[]
sessions Session[]
}
```
关键字段说明：
- `id`: 全局唯一标识符，使用 CUID 算法生成
- `name`: 可选的追踪名称，便于识别
- `userId`: 终端用户标识，用于多用户场景
- `metadata`: 灵活 JSON 字段存储附加信息
- `release`: 发布版本标签
- `version`: 追踪数据版本
资料来源：[packages/shared/prisma/schema.prisma]()
### Observation 表结构
`Observation` 表存储追踪内的具体调用单元，支持多种事件类型：
```prisma
model Observation {
id String @id @default(cuid())
traceId String
type ObservationType
name String?
startTime DateTime
endTime DateTime?
metadata Json?
// 嵌套调用
parentObservationId String?
parentObservation Observation? @relation(...)
childObservations Observation[]
// 嵌入内容
input String?
output String?
usage Json?
parameters Json?
// 成本追踪
promptTokens Int?
completionTokens Int?
totalTokens Int?
unitDollarPrice Float?
totalDollarPrice Float?
scores Score[]
}
```
`ObservationType` 枚举定义事件类型：
- `CHAT Spike`: 聊天消息
- `COMPLETION`: 文本补全
- `CHUNK`: 流式数据块
- `GENERATION`: 生成事件
- `EVENT`: 通用事件
- `SPAN`: 跨度（包含子事件）
资料来源：[packages/shared/prisma/schema.prisma]()
### Score 评分设计
评分系统支持多维度评估，采用灵活的 JSON 结构：
```prisma
model Score {
id String @id @default(cuid())
name String
value Float
dataType ScoreDataType
// 评分来源
source ScoreSource
// 关联对象
traceId String?
observationId String?
// 评分者信息
authorId String?
comment String?
createdAt DateTime @default(now())
}
```
评分数据类型：
- `NUMERIC`: 数值型评分
- `CATEGORICAL`: 分类型评分
- `BOOLEAN`: 布尔型评分
评分来源包括 `API`、`INGESTION`、`EVALUATION`、`USER`、`BENCHMARK` 等。
资料来源：[packages/shared/prisma/schema.prisma]()
资料来源：[packages/shared/src/features/scores/interfaces/README.md]()
## ClickHouse 事件存储
### 事件存储架构
ClickHouse 作为列式存储数据库，专门用于高吞吐量的事件数据和分析查询。所有通过 Ingestion API 摄入的事件都会写入 ClickHouse，形成持久化的事件流。
```mermaid
graph LR
A[SDK Events] --> B[Ingestion API]
B --> C[Event Validation]
C --> D[Queue Event]
D --> E[Worker Processing]
E --> F[(ClickHouse)]
E --> G[(PostgreSQL)]
F --> H[Analytics Queries]
G --> I[Relational Queries]
```
事件数据按时间分区存储，支持高效的时间范围查询。数据采用分层设计：原始事件存储在 ClickHouse，经过处理的关系数据同步到 PostgreSQL。
资料来源：[packages/shared/clickhouse/migrations/clustered]()
资料来源：[worker/src/scripts/refillQueueEvent/README.md]()
### ClickHouse 表结构
ClickHouse 采用物化视图和合并树引擎优化查询性能：
```sql
CREATE TABLE events (
id UUID,
project_id String,
trace_id String,
type String,
body String,
event_timestamp DateTime,
created_at DateTime
) ENGINE = MergeTree()
ORDER BY (project_id, event_timestamp, id)
PARTITION BY toYYYYMM(event_timestamp);
```
关键设计决策：
- 使用 `project_id` 作为排序键首位，支持项目级高效过滤
- 按月份分区，便于历史数据管理
- 事件体存储为字符串，支持灵活的反序列化
资料来源：[packages/shared/clickhouse/migrations/clustered]()
### OTEL 事件格式
OpenTelemetry 兼容事件使用特定路径格式存储：
```
otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json
```
这种层次化路径设计允许 S3 兼容存储和 ClickHouse 联合查询，实现边缘缓存和计算分离。
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()
## Redis 缓存与队列
### 队列架构
Langfuse 使用 BullMQ（基于 Redis）实现异步任务处理：
```mermaid
graph TB
subgraph 队列系统
A[OtelIngestionQueue] --> B[Ingestion Worker]
C[IngestionSecondaryQueue] --> D[Secondary Worker]
E[PromptCacheQueue] --> F[Cache Worker]
end
subgraph 数据流
B --> G[(ClickHouse)]
D --> H[(PostgreSQL)]
F --> I[(Cache)]
end
```
主要队列类型：
| 队列名称 | 用途 | 数据目标 |
|----------|------|----------|
| `OtelIngestionQueue` | OTEL 格式事件处理 | ClickHouse |
| `IngestionSecondaryQueue` | 标准事件处理 | PostgreSQL + ClickHouse |
| `PromptCacheQueue` | 提示词缓存更新 | Redis Cache |
资料来源：[worker/src/scripts/refillQueueEvent/README.md]()
### 缓存策略
提示词模板使用 Redis 缓存加速访问：
```typescript
interface PromptCacheEntry {
promptId: string;
content: string;
version: number;
expiresAt: number;
}
```
缓存失效采用主动更新模式：当提示词更新时，通过队列触发缓存刷新，确保多实例部署的一致性。
资料来源：[web/src/features/mcp/README.md]()
## 数据流与同步
### 事件摄取流程
```mermaid
sequenceDiagram
participant SDK
participant API as Ingestion API
participant Queue as BullMQ
participant Worker
participant CH as ClickHouse
participant PG as PostgreSQL
SDK->>API: POST /ingestion
API->>API: Validate & Transform
API->>Queue: Enqueue Event
API-->>SDK: 200 OK
Queue->>Worker: Dequeue Job
Worker->>CH: Insert Event
Worker->>PG: Upsert Entity
Worker->>Worker: Index & Compute
```
事件摄取遵循写入放大模式：单次 API 调用触发多次数据写入，通过队列解耦确保响应延迟最小化。
资料来源：[packages/shared/src/server/repositories]()
### 批量处理与检查点
摄取脚本支持断点续传机制：
```typescript
interface BatchProgress {
totalRows: number;
processedRows: number;
queuedCount: number;
skippedCount: number;
errorCount: number;
}
```
检查点文件保存当前处理位置，失败后可从上次成功位置恢复，保证大规模数据导入的可靠性。
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()
## 查询优化
### 索引策略
PostgreSQL 表设计包含多层索引优化：
```sql
-- 复合索引支持项目级快速查询
CREATE INDEX idx_traces_project_created
ON traces(project_id, created_at DESC);
-- 文本搜索索引
CREATE INDEX idx_traces_name_gin
ON traces USING gin(name gin_trgm_ops);
-- 关系索引维护查询性能
CREATE INDEX idx_observations_trace
ON observations(trace_id, start_time DESC);
```
### ClickHouse 查询模式
分析查询使用物化视图聚合：
```sql
CREATE MATERIALIZED VIEW score_stats_mv
ENGINE = SummingMergeTree()
ORDER BY (project_id, score_name, period)
AS SELECT
project_id,
score_name,
toDate(timestamp) as period,
count() as count,
avg(value) as avg_value,
quantile(0.5)(value) as p50
FROM raw_events
WHERE type = 'score'
GROUP BY project_id, score_name, period;
```
资料来源：[packages/shared/src/tableDefinitions]()
## 安全与隔离
### 组织级数据隔离
所有查询必须通过项目作用域验证：
```typescript
interface AuthCheck {
validKey: boolean;
scope: {
projectId: string;
accessLevel: "project" | "org";
};
}
```
API 密钥与项目绑定，跨项目访问通过组织成员关系控制。
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()
### 敏感数据处理
用户上传的 `metadata` 字段支持服务端过滤：
```typescript
interface FilterConfig {
fieldPath: string;
action: "REDACT" | "REMOVE" | "ALLOW";
}
```
配置化的数据过滤规则确保敏感信息不会出现在日志或分析结果中。
## 总结
Langfuse 的数据库设计体现了现代 SaaS 应用的多存储策略：
- **PostgreSQL** 提供强一致性的关系数据存储
- **ClickHouse** 处理高吞吐量分析工作负载
- **Redis** 实现异步处理和高速缓存
三层架构通过事件驱动模式松耦合，支持水平扩展同时保持数据完整性。Repository 模式封装数据访问逻辑，隐藏底层存储细节，便于未来架构演进。
资料来源：[packages/shared/src/server/repositories]()
资料来源：[packages/shared/prisma/schema.prisma]()
---
## 追踪系统
### 相关页面
相关主题：[数据库设计](#p-database)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/shared/src/domain/traces.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/traces.ts)
- [packages/shared/src/domain/observations.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/observations.ts)
- [packages/shared/src/server/ingestion](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/ingestion)
- [packages/shared/src/server/otel](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/otel)
- [packages/shared/src/server/repositories/traces.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/repositories/traces.ts)
- [packages/shared/src/server/repositories/observations.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/repositories/observations.ts)
# 追踪系统
## 概述
追踪系统（Tracing System）是 Langfuse 的核心功能模块，负责收集、存储和展示 LLM 应用执行过程中的完整调用链路。该系统基于 OpenTelemetry 标准构建，支持多种观察类型，能够帮助开发者监控、分析和优化 AI 应用的行为。
追踪系统的主要职责包括：
- **链路追踪**：记录完整的请求调用链路，包括输入、输出和中间过程
- **观察类型支持**：支持 SPAN（跨度）、GENERATION（生成）、EVENT（事件）等多种观察类型
- **层级结构**：通过父子关系构建树形结构，展现调用嵌套关系
- **元数据管理**：附加和解析丰富的上下文元数据
- **评分集成**：与评分系统集成，支持评估执行效果的追踪
资料来源：[packages/shared/src/domain/traces.ts]()
---
## 核心数据模型
### Trace（追踪）
Trace 是整个追踪系统的顶层容器，代表一次完整的请求或会话。每个 Trace 包含以下关键属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| id | string | 追踪的唯一标识符 |
| name | string | 追踪名称，用于快速识别 |
| projectId | string | 所属项目 ID |
| userId | string | 用户标识 |
| sessionId | string | 会话标识 |
| metadata | JSON | 附加的元数据 |
| release | string | 发布版本 |
| version | string | 追踪版本 |
| tags | string[] | 标签数组 |
| environment | string | 环境（default 等） |
| bookmarked | boolean | 是否收藏 |
| input | JSON | 输入数据 |
| output | JSON | 输出数据 |
| latency | number | 总延迟（秒） |
| createdAt | DateTime | 创建时间 |
资料来源：[packages/shared/src/domain/traces.ts:1-20]()
### Observation（观察）
Observation 是 Trace 的子节点，代表追踪中的一个具体操作或事件。支持四种类型：
| 类型 | 说明 | 使用场景 |
|------|------|----------|
| TRACE | 追踪容器根节点 | 包装整个追踪结构 |
| SPAN | 跨度 | 标记一段代码执行区间 |
| GENERATION | 生成 | 记录 LLM 生成操作 |
| EVENT | 事件 | 记录离散的时间点事件 |
每个 Observation 包含以下属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| id | string | 观察的唯一标识符 |
| traceId | string | 所属追踪 ID |
| parentObservationId | string | 父观察 ID（用于构建层级） |
| type | ObservationType | 观察类型 |
| name | string | 观察名称 |
| startTime | DateTime | 开始时间 |
| endTime | DateTime | 结束时间 |
| metadata | JSON | 元数据 |
| input | JSON | 输入内容 |
| output | JSON | 输出内容 |
| model | string | 使用的模型（如适用） |
| modelParameters | JSON | 模型参数 |
| usage | Usage | Token 使用量 |
| level | string | 日志级别 |
| statusMessage | string | 状态消息 |
资料来源：[packages/shared/src/domain/observations.ts]()
---
## 系统架构
### 整体架构图
```mermaid
graph TD
subgraph 客户端层
SDK[SDK / OpenTelemetry SDK]
MCP[MCP Server]
end
subgraph 摄取层
IngestionAPI[摄取 API]
OTELEndpoint[OTEL Endpoint]
end
subgraph 处理层
Validation[数据验证]
Transform[数据转换]
Queue[消息队列]
end
subgraph 存储层
PostgreSQL[(PostgreSQL)]
ClickHouse[(ClickHouse)]
Redis[(Redis)]
end
subgraph 查询层
TracesRepo[Traces Repository]
ObservationsRepo[Observations Repository]
ScoreRepo[Score Repository]
end
subgraph 展示层
TraceTree[追踪树构建]
JsonViewer[JSON 查看器]
Analytics[分析面板]
end
SDK --> IngestionAPI
MCP --> IngestionAPI
SDK --> OTELEndpoint
IngestionAPI --> Validation
OTELEndpoint --> Validation
Validation --> Transform
Transform --> Queue
Queue --> PostgreSQL
Queue --> ClickHouse
TracesRepo --> PostgreSQL
ObservationsRepo --> ClickHouse
ScoreRepo --> PostgreSQL
TraceTree --> ObservationsRepo
JsonViewer --> TracesRepo
Analytics --> ScoreRepo
```
### 数据流向
```mermaid
graph LR
A[事件创建] --> B[事件摄取]
B --> C{验证}
C -->|通过| D[写入队列]
C -->|失败| E[错误日志]
D --> F[异步处理]
F --> G[ClickHouse]
F --> H[PostgreSQL]
G --> I[UI 展示]
H --> I
```
---
## 摄取系统
### 标准摄取流程
Langfuse 支持两种事件摄取方式：标准摄取和 OpenTelemetry（OTEL）摄取。
#### 标准摄取端点
标准摄取使用以下格式的 S3 键路径：
```
{projectId}/{type}/{eventBodyId}/{eventId}.json
```
摄取请求体结构：
```json
{
"authCheck": {
"validKey": true,
"scope": { "projectId": "" }
},
"data": {
"eventBodyId": "",
"fileKey": "",
"type": "-create"
}
}
```
事件经过验证后被加入 `IngestionSecondaryQueue` 队列处理。
资料来源：[packages/shared/src/server/ingestion]()
#### OTEL 摄取端点
OTEL 格式使用更详细的路径结构，支持标准化的遥测数据格式：
```
otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json
```
OTEL 请求体结构：
```json
{
"authCheck": {
"validKey": true,
"scope": { "projectId": "", "accessLevel": "project" }
},
"data": {
"fileKey": "otel///////.json"
}
}
```
OTEL 事件被加入 `OtelIngestionQueue` 队列处理。
资料来源：[packages/shared/src/server/otel]()
### 验证与转换
摄取流程包含严格的数据验证步骤：
1. **身份验证检查**：验证 API Key 和项目权限
2. **Schema 验证**：使用 Zod 进行类型验证
3. **数据转换**：将原始事件转换为内部数据模型
4. **队列分发**：根据事件类型分发到对应队列
---
## 存储层
### 多存储架构
Langfuse 采用混合存储策略，根据数据特性选择最优存储：
| 数据类型 | 存储引擎 | 说明 |
|----------|----------|------|
| Trace 元数据 | PostgreSQL | 结构化查询，事务支持 |
| Observation 数据 | ClickHouse | 时序数据，分析查询优化 |
| 缓存数据 | Redis | 热点数据加速访问 |
| 大型 JSON | S3 | 存储 input/output 等大字段 |
### Traces 仓库
`TracesRepository` 负责 Trace 的 CRUD 操作：
- 创建新追踪记录
- 更新追踪元数据
- 查询追踪列表（支持分页、过滤、排序）
- 获取单个追踪详情
资料来源：[packages/shared/src/server/repositories/traces.ts]()
### Observations 仓库
`ObservationsRepository` 负责 Observation 的管理：
- 创建观察记录
- 更新观察数据
- 构建树形结构查询
- 批量查询追踪下的所有观察
资料来源：[packages/shared/src/server/repositories/observations.ts]()
---
## UI 展示系统
### 追踪树构建
追踪数据在 UI 中以树形结构展示。核心构建逻辑位于 `buildTraceUiData` 函数：
```typescript
// 传统追踪：单一 TRACE 根节点 + 子观察节点
const result = buildTraceUiData(trace, observations);
// 结果结构
{
roots: [
{
id: "trace-{traceId}",
type: "TRACE",
name: "{traceName}",
children: [
{ id: "{obsId}", type: "SPAN|GENERATION|EVENT", ... }
]
}
]
}
```
树构建使用**显式栈迭代**而非递归，以避免深度嵌套导致的栈溢出问题：
```typescript
// ❌ 递归方式（深度 1000+ 可能栈溢出）
function traverse(node: TreeNode) {
process(node);
node.children.forEach((child) => traverse(child));
}
// ✅ 迭代方式（安全处理任意深度）
function traverse(rootNode: TreeNode) {
const stack = [rootNode];
while (stack.length > 0) {
const node = stack.pop()!;
process(node);
node.children.forEach((child) => stack.push(child));
}
}
```
资料来源：[web/src/components/trace/lib/tree-building.clienttest.ts]()
### 追踪页面组件
追踪详情页面使用 `Page` 组件包装，确保一致的布局体验：
```tsx
```
### JSON 查看器
追踪详情使用 `AdvancedJsonViewer` 组件展示，支持：
- 树形结构展开/折叠
- 关键字搜索（客户端内存搜索）
- 虚拟化渲染（支持大数据集）
- 自定义主题
---
## 元数据系统
### 元数据解析
追踪系统支持从元数据中提取特定字段：
```typescript
export const resolveEvalExecutionMetadata = (
parsedMetadata: unknown
): string | null => {
try {
if (typeof parsedMetadata !== "object" || parsedMetadata === null)
return null;
return (parsedMetadata as Record)[
"target_trace_id"
] as string;
} catch {
return null;
}
};
```
此函数用于关联评估执行与目标追踪，实现评估结果的溯源。
资料来源：[web/src/components/trace/lib/resolve-metadata.ts]()
### 过滤器与查询编码
追踪支持丰富的过滤条件，使用 URL 编码存储：
```typescript
// 支持的过滤类型
const filterTypes = {
datetime: Date, // 日期时间过滤
number: Number, // 数值过滤
numberObject: Number, // 对象内数值过滤
stringOptions: string[], // 字符串选项
arrayOptions: string[], // 数组选项
categoryOptions: string[], // 分类选项
boolean: boolean // 布尔过滤
};
```
资料来源：[web/src/features/filters/lib/filter-query-encoding.ts]()
---
## 评分集成
### 评分接口
追踪系统与评分系统深度集成，支持在追踪级别附加评分：
| API 版本 | GET 要求 | 新增字段 |
|----------|----------|----------|
| V1 | 必须提供 `traceId` | 仅支持追踪级评分 |
| V2 | `traceId` 可选 | 支持 `sessionId` |
资料来源：[packages/shared/src/features/scores/interfaces/README.md]()
### 评分解析
评分分析模块提供统计计算和可视化：
```typescript
// 评分一致性解读
function interpretAgreement(agreement: number): InterpretationResult {
if (agreement >= 0.9) {
return { strength: "Excellent", color: "green" };
}
if (agreement >= 0.8) {
return { strength: "Good", color: "blue" };
}
// ...
}
// MAE 解读（支持相对误差计算）
function interpretMAE(
mae: number | null,
scale?: { min: number; max: number }
): InterpretationResult
```
资料来源：[web/src/features/score-analytics/lib/statistics-utils.ts]()
---
## 开发工具
### 追踪回放脚本
`replayIngestionEventsV2` 脚本支持从 CSV 文件回放摄取事件：
```bash
pnpm run --filter=worker replay-ingestion-events-v2 \
--input=events.csv \
--url=http://localhost:3000 \
--rate-limit=100
```
特性：
- **断点续传**：自动保存检查点，失败后可恢复
- **速率限制**：客户端与服务端双重限流
- **重试机制**：临时错误自动重试（最多 3 次）
- **错误日志**：失败事件记录到 `errors.csv`
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()
### 队列填充脚本
`refillQueueEvent` 脚本用于本地回填队列：
```bash
# 1. 创建事件文件 worker/events.jsonl
{"projectId": "project-123", "orgId": "org-456"}
# 2. 配置环境变量
REDIS_CONNECTION_STRING=redis://:secret@127.0.0.1:6379
# 3. 运行脚本
pnpm run --filter=worker refill-queue-event
```
资料来源：[worker/src/scripts/refillQueueEvent/README.md]()
---
## 最佳实践
### 追踪命名规范
追踪名称建议遵循格式：`{操作}: {唯一标识}`，例如：
- `chat-completion: msg-abc123`
- `agent-execution: run-xyz789`
### 嵌套层级控制
为保证 UI 性能和可读性：
- 建议单个追踪的观察节点不超过 1000 个
- 深度嵌套建议拆分为多个子追踪
- 使用 EVENT 类型记录关键时间点，而非创建大量小 SPAN
### 元数据组织
元数据应包含：
- **上下文信息**：请求来源、用户特征
- **性能指标**：各阶段耗时、Token 使用量
- **调试信息**：内部标识符、版本号
---
## 相关文档
| 模块 | 路径 | 说明 |
|------|------|------|
| 领域模型 | `packages/shared/src/domain/` | Trace 和 Observation 的核心定义 |
| 摄取服务 | `packages/shared/src/server/ingestion/` | 数据摄取 API |
| OTEL 支持 | `packages/shared/src/server/otel/` | OpenTelemetry 集成 |
| 仓库层 | `packages/shared/src/server/repositories/` | 数据库操作封装 |
| UI 组件 | `web/src/components/trace/` | 追踪展示组件 |
| 评分系统 | `web/src/features/score-analytics/` | 评分分析与可视化 |
---
## 提示词管理
### 相关页面
相关主题：[数据库设计](#p-database)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/shared/src/domain/prompts.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/prompts.ts)
- [packages/shared/src/features/prompts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/prompts)
- [packages/shared/src/server/services/PromptService](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/services/PromptService)
- [web/src/features/prompts](https://github.com/langfuse/langfuse/blob/main/web/src/features/prompts)
- [web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)
- [packages/shared/src/tableDefinitions/promptsTable.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/tableDefinitions/promptsTable.ts)
# 提示词管理
提示词管理（Prompt Management）是 Langfuse 平台的核心功能之一，它提供了对提示词（Prompts）的创建、版本控制、组合、缓存和分发的完整生命周期管理。通过 Langfuse 的提示词管理系统，用户可以集中管理所有项目的提示词，支持版本标签、依赖引用、API 调用以及 MCP（Model Context Protocol）集成。
## 核心概念
### 提示词实体
Langfuse 中的提示词是一个包含名称、版本、内容和元数据的实体。每个提示词具有以下核心属性：
| 属性 | 说明 |
|------|------|
| `name` | 提示词的唯一标识名称 |
| `version` | 自动递增的版本号 |
| `type` | 提示词类型（text 或 chat） |
| `config` | 提示词配置（温度、最大 token 等） |
| `labels` | 版本标签数组（如 production、development） |
| `prompt` | 提示词内容或消息数组 |
| `createdAt` | 创建时间戳 |
资料来源：[packages/shared/src/domain/prompts.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/prompts.ts)
### 提示词类型
Langfuse 支持两种提示词类型：
**文本提示词（Text Prompt）**
- 用于简单的文本补全任务
- `prompt` 字段存储纯文本内容
**聊天提示词（Chat Prompt）**
- 用于 OpenAI 风格的聊天接口
- `prompt` 字段存储消息数组，每条消息包含 `role` 和 `content`
资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)
## 系统架构
### 整体架构
```mermaid
graph TD
subgraph 客户端层
MCP[ MCP Server ]
API[ REST API ]
WebUI[ Web 前端 ]
end
subgraph 服务层
PromptService[ PromptService ]
PromptCache[ Redis Cache ]
PromptDB[( PostgreSQL )]
end
MCP -->|getPrompt/createPrompt| PromptService
API -->|CRUD 操作| PromptService
WebUI -->|管理界面| PromptService
PromptService -->|缓存读写| PromptCache
PromptService -->|持久化| PromptDB
```
### 数据存储
Langfuse 使用 PostgreSQL 作为提示词的持久化存储，并通过 Redis 实现缓存层以提升读取性能。
```mermaid
graph LR
A[读请求] --> B{检查 Redis}
B -->|缓存命中| C[返回缓存数据]
B -->|缓存未命中| D[查询 PostgreSQL]
D --> E[写入 Redis]
E --> C
```
资料来源：[web/src/features/prompts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/prompts)
## 缓存策略
### 缓存结构
提示词的缓存使用 Redis 管理，缓存键格式如下：
```
prompt:::
```
这意味着：
- 同一提示词名称可能对应多个缓存键
- 具有多个标签的提示词会在缓存中多次出现
### 缓存操作流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant Cache as Redis Cache
participant Lock as Redis Lock
participant DB as PostgreSQL
Client->>Cache: 读取提示词
Cache->>Cache: 检查缓存键
alt 缓存命中
Cache-->>Client: 返回缓存数据
Cache->>Cache: 重置 TTL
else 缓存未命中 或 锁存在
Cache-->>DB: 查询数据库
DB-->>Cache: 返回提示词数据
Cache-->>Client: 返回数据并缓存
end
Note over Lock,DB: 更新提示词时
Lock->>Lock: 获取分布式锁
Lock->>Cache: 清除所有相关缓存键
Lock->>DB: 执行数据库更新
Lock->>Lock: 释放锁
```
### 关键设计原则
1. **从不更新缓存**：当提示词更新时，系统会删除所有相关的缓存条目，而不是修改它们
2. **分布式锁保护**：使用 Redis 锁确保并发更新的安全性
3. **操作顺序**：先获取锁 → 失效缓存 → 执行数据库操作 → 释放锁
资料来源：[web/src/features/prompts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/prompts)
## MCP 集成
Langfuse 提供了 MCP（Model Context Protocol）服务器集成，允许外部工具和客户端程序访问提示词管理功能。
### MCP 工具列表
| 工具名称 | 功能 | 类型 |
|----------|------|------|
| `getPrompt` | 获取完全解析的提示词（包含依赖） | 只读 |
| `getPromptUnresolved` | 获取原始提示词（保留依赖标签） | 只读 |
| `listPrompts` | 列出所有提示词（支持过滤和分页） | 只读 |
| `createTextPrompt` | 创建新的文本提示词版本 | 写入 |
| `createChatPrompt` | 创建新的聊天提示词版本 | 写入 |
| `updatePromptLabels` | 更新提示词标签 | 写入 |
### 提示词解析模式
MCP 服务提供两种提示词获取模式：
**完全解析模式（getPrompt）**
- 用于获取可直接发送给 LLM 的最终提示词
- 递归解析所有依赖标签
- 返回包含完整内容的提示词
**原始模式（getPromptUnresolved）**
- 用于分析提示词组合结构
- 保留 `@@@langfusePrompt:name=xxx|label=yyy@@@` 依赖标签
- 有助于调试和理解提示词依赖关系
资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)
## 提示词组合
### 依赖标签语法
Langfuse 支持提示词组合功能，允许一个提示词引用其他提示词。依赖标签语法如下：
```
@@@langfusePrompt:name=|label=@@@
```
### 组合示例
```
输入: "You are helpful. @@@langfusePrompt:name=base-rules|label=production@@@"
输出: "You are helpful. Always be kind and respectful."
```
### 使用场景
- **提示词堆叠**：将基础规则与具体任务提示词组合
- **依赖链分析**：使用 `getPromptUnresolved` 调试依赖关系
- **构建工具**：开发管理提示词组合的自动化工具
```mermaid
graph TD
A[主提示词] -->|依赖| B[基础规则提示词]
A -->|依赖| C[角色定义提示词]
B -->|依赖| D[通用指令提示词]
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#fff3e0
style D fill:#f3e5f5
```
## API 接口
### 创建提示词
**文本提示词**
```typescript
createTextPrompt(params: {
projectId: string;
promptName: string;
prompt: string;
config?: PromptConfig;
labels?: string[];
})
```
**聊天提示词**
```typescript
createChatPrompt(params: {
projectId: string;
promptName: string;
messages: ChatMessage[];
config?: PromptConfig;
labels?: string[];
})
```
### 查询提示词
```typescript
listPrompts(params: {
projectId: string;
name?: string; // 可选：按名称过滤
label?: string; // 可选：按标签过滤
tag?: string; // 可选：按标签过滤
updatedAtStart?: Date;
updatedAtEnd?: Date;
page?: number;
limit?: number;
})
```
## 版本控制与标签
### 版本管理
每个提示词版本具有自动递增的版本号。创建新版本时：
1. 版本号自动加一
2. 可选择性地添加标签（如 `production`、`dev`）
3. 版本记录创建时间戳
### 标签系统
标签用于标识提示词的用途或环境：
| 标签示例 | 用途 |
|----------|------|
| `production` | 生产环境使用的版本 |
| `staging` | 测试环境使用的版本 |
| `experiment` | 实验性版本 |
| `archived` | 已归档的旧版本 |
### 标签更新操作
`updatePromptLabels` 工具允许：
- 添加新标签到现有版本
- 将标签从一个版本移动到另一个版本
- 删除不需要的标签
## 数据库模型
提示词表结构定义：
```typescript
interface PromptTable {
id: string; // UUID 主键
project_id: string; // 项目 ID
name: string; // 提示词名称
version: number; // 版本号
type: "text" | "chat"; // 提示词类型
prompt: string; // 提示词内容
config: object; // 配置（JSON）
labels: string[]; // 标签数组
created_at: Date; // 创建时间
updated_at: Date; // 更新时间
}
```
资料来源：[packages/shared/src/tableDefinitions/promptsTable.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/tableDefinitions/promptsTable.ts)
## 审计日志
所有写入操作（创建、更新标签）会自动创建审计日志条目，包含：
- 操作前状态快照
- 操作后状态快照
- 操作时间戳
- 操作者信息
## 安全与权限
### 访问控制
MCP 集成使用 BasicAuth 认证：
```bash
# 生成 Basic Auth Token
echo -n "pk-lf-your-public-key:sk-lf-your-secret-key" | base64
```
### 权限级别
| 权限级别 | 说明 |
|----------|------|
| `project` | 项目级访问权限 |
| `org` | 组织级访问权限 |
| `admin` | 管理员权限 |
### 工具注解
MCP 工具包含安全提示注解：
- `readOnly: true`：安全操作，无需确认（如 `getPrompt`、`listPrompts`）
- `destructive: true`：修改数据的操作（如 `createTextPrompt`、`createChatPrompt`）
客户端程序可以根据这些注解自动批准只读操作，或在执行破坏性操作时要求用户确认。
## 最佳实践
### 命名规范
- 使用描述性名称：`customer-support-greeting` 而非 `prompt-1`
- 统一命名风格：建议使用 kebab-case 或 camelCase
- 包含版本或环境信息：`prompt-name:production`
### 标签使用策略
1. 生产环境使用 `production` 标签
2. 开发和测试使用 `dev` 或 `staging` 标签
3. 避免在标签中包含敏感信息
4. 定期清理不再使用的标签
### 缓存优化
1. 避免频繁更新提示词，以减少缓存失效开销
2. 使用标签而非版本号来引用提示词（标签更稳定）
3. 监控缓存命中率，及时调整缓存策略
## 总结
Langfuse 的提示词管理系统提供了企业级的提示词管理能力，包括：
- **版本控制**：自动版本管理和标签系统
- **组合能力**：支持提示词依赖和复用
- **高性能**：Redis 缓存和锁机制确保并发安全
- **标准化接口**：REST API 和 MCP 集成支持多种客户端
- **审计追踪**：完整的操作日志记录
---
## 评估系统
### 相关页面
相关主题：[数据集管理](#p-datasets), [追踪系统](#p-tracing)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/shared/src/domain/score-configs.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/score-configs.ts)
- [packages/shared/src/domain/scores.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/scores.ts)
- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
- [web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)
- [web/src/features/score-analytics/lib/statistics-utils.ts](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/lib/statistics-utils.ts)
# 评估系统
## 概述
Langfuse 的评估系统（Evaluation System）是用于衡量和分析 LLM 应用输出的核心模块。该系统提供了一套完整的评分（Score）管理机制，包括评分的定义、存储、分析和可视化功能。评估系统帮助开发者量化 LLM 生成内容的质量，支持自定义评分规则，并通过统计分析提供对模型性能的洞察。
Langfuse 采用双轨 API 设计，支持 v1（遗留版本，仅支持 trace 级别评分）和 v2（当前版本，支持 trace、session 和数据集运行级别的评分）。资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
---
## 核心数据模型
### 评分（Score）
评分是评估系统的基本单元，用于记录对 trace、session 或数据集运行项的评估结果。
| 属性 | 类型 | 说明 |
|------|------|------|
| `id` | string | 评分唯一标识符 |
| `name` | string | 评分名称（如 "accuracy", "relevance"） |
| `value` | number \| string \| boolean | 评分的实际值 |
| `dataType` | "NUMERIC" \| "CATEGORICAL" \| "BOOLEAN" | 数据类型 |
| `traceId` | string | 关联的 trace ID（v1 API 必需） |
| `sessionId` | string | 关联的 session ID（v2 API 支持） |
| `observationId` | string | 关联的 observation ID |
| `source` | "API" \| "APP" \| "EVALUATION" \| "LLM" | 评分来源 |
| `comment` | string | 可选的评分备注 |
| `metadata` | object | 附加元数据 |
| `createdAt` | DateTime | 创建时间 |
| `updatedAt` | DateTime | 更新时间 |
资料来源：[packages/shared/src/domain/scores.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/scores.ts)
### 评分配置（ScoreConfig）
评分配置定义了项目中的评分规则和元数据，确保评分的一致性和可解释性。
| 属性 | 类型 | 说明 |
|------|------|------|
| `id` | string | 配置唯一标识符 |
| `projectId` | string | 所属项目 ID |
| `name` | string | 评分名称（项目内唯一） |
| `dataType` | "NUMERIC" \| "CATEGORICAL" \| "BOOLEAN" | 期望的数据类型 |
| `categories` | string[] | 枚举值列表（categorical 类型必需） |
| `description` | string | 评分说明文档 |
| `valueRange` | { min?, max? } | 数值范围约束（numeric 类型） |
| `createdAt` | DateTime | 创建时间 |
| `updatedAt` | DateTime | 更新时间 |
资料来源：[packages/shared/src/domain/score-configs.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/score-configs.ts)
---
## 系统架构
```mermaid
graph TD
subgraph 前端层
A[Web UI] --> B[Score Analytics 组件]
A --> C[评分配置管理]
end
subgraph API 层
D[v1 API] --> E[Scores Endpoints]
F[v2 API] --> E
E --> G[Score Router]
end
subgraph 服务层
G --> H[Score Service]
G --> I[Score Analytics Service]
end
subgraph 数据层
H --> J[(PostgreSQL)]
I --> K[(ClickHouse)]
end
subgraph Worker 层
L[Evaluation Worker] --> M[评分计算任务]
M --> I
end
```
---
## 评分类型
Langfuse 支持三种评分数据类型，适用于不同的评估场景：
### 数值型（NUMERIC）
用于连续数值的评分，如准确率得分（0-1）、延迟（毫秒）、成本（美元）等。
```typescript
{
name: "accuracy",
value: 0.95,
dataType: "NUMERIC",
dataType: {
min: 0,
max: 1
}
}
```
### 类别型（CATEGORICAL）
用于离散的分类标签，如评级（A/B/C）、质量等级（优秀/良好/一般）等。
```typescript
{
name: "quality",
value: "excellent",
dataType: "CATEGORICAL",
categories: ["excellent", "good", "fair", "poor"]
}
```
### 布尔型（BOOLEAN）
用于二元判断，如是否通过、是否合规、是否有毒等。
```typescript
{
name: "is_valid",
value: true,
dataType: "BOOLEAN"
}
```
资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
---
## 评分来源
| 来源标识 | 说明 | 典型使用场景 |
|----------|------|-------------|
| `API` | 通过 API 直接提交 | 外部评估系统集成 |
| `APP` | 通过 Langfuse UI 手动创建 | 人工审核评分 |
| `EVALUATION` | 通过评估任务自动生成 | 自动化测试套件 |
| `LLM` | 由 LLM 作为评判者生成 | LLM-as-Judge 评估 |
资料来源：[packages/shared/src/domain/scores.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/scores.ts)
---
## 评分分析功能
### Score Analytics Provider
`ScoreAnalyticsProvider` 是前端核心组件，用于包装评分分析数据并向子组件提供上下文。
```tsx
```
### Hooks 层
| Hook | 职责 |
|------|------|
| `useScoreAnalyticsQuery` | 从 API 获取数据并执行一次转换 |
| `useScoreAnalytics` | 从 Provider 上下文获取分析数据 |
资料来源：[web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)
### 数据转换管道
评分数据从 API 返回后需经过多层转换处理：
```mermaid
graph LR
A[API Raw Data] --> B[Extract Categories]
B --> C[Fill Distribution Bins]
C --> D[Generate Bin Labels]
D --> E[Transform Heatmap]
E --> F[Calculate Mode Metrics]
F --> G[Fill Time Series Gaps]
G --> H[Namespace Categorical]
H --> I[ScoreAnalyticsData]
```
所有转换逻辑均位于 `useScoreAnalyticsQuery` Hook 中，使用 `useMemo` 进行记忆化，确保数据仅转换一次。
资料来源：[web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)
---
## 统计分析工具
### 一致性解释（interpretAgreement）
用于评估两个评分之间的一致性程度：
| 一致性范围 | 强度等级 | 颜色标识 |
|-----------|----------|----------|
| ≥ 0.9 | Excellent | green |
| ≥ 0.8 | Good | blue |
| ≥ 0.6 | Fair | yellow |
| ≥ 0.4 | Poor | orange |
| < 0.4 | Very Poor | red |
```typescript
export function interpretAgreement(
agreement: number | null
): InterpretationResult {
if (agreement >= 0.9) {
return {
strength: "Excellent",
color: "green",
description: `${percentage}% of predictions match`,
};
}
// ... 其他阈值
}
```
资料来源：[web/src/features/score-analytics/lib/statistics-utils.ts](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/lib/statistics-utils.ts)
### MAE 解释（interpretMAE）
Mean Absolute Error 的上下文相关解释：
```typescript
export function interpretMAE(
mae: number | null,
scale?: { min: number; max: number }
): InterpretationResult
```
当提供 `scale` 参数时，系统会计算相对误差以提供更有意义的解释。
资料来源：[web/src/features/score-analytics/lib/statistics-utils.ts](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/lib/statistics-utils.ts)
---
## API 版本差异
| 特性 | v1 API | v2 API |
|------|--------|--------|
| `traceId` | **必需** | 可选 |
| `sessionId` | 不支持 | 支持 |
| 适用范围 | 仅 trace 级别评分 | trace、session、数据集运行 |
| 生命周期 | 遗留版本 | 当前推荐版本 |
> **注意**：POST 和 DELETE API 在 v1 和 v2 中保持一致，继续支持所有评分类型。
资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
---
## 文件结构
```
packages/shared/src/
├── domain/
│ ├── score-configs.ts # 评分配置领域模型
│ └── scores.ts # 评分领域模型
└── features/scores/
└── interfaces/ # 接口定义
├── api/
│ ├── v1/ # 遗留 API 类型
│ ├── v2/ # 当前 API 类型
│ └── shared.ts # 共享类型
├── application/ # 应用层验证
├── ingestion/ # 摄取层类型
└── ui/ # UI 简化类型
web/src/features/
└── score-analytics/
├── components/ # 评分分析组件
│ └── ScoreAnalyticsProvider.tsx
├── hooks/
│ └── useScoreAnalyticsQuery.ts
├── lib/
│ ├── analytics-url-state.ts
│ ├── clickhouse-time-utils.ts
│ ├── color-scales.ts
│ ├── heatmap-utils.ts
│ ├── score-formatter.ts
│ ├── scoreAnalyticsTransformers.ts
│ └── statistics-utils.ts
└── server/
└── scoreAnalyticsRouter.ts
worker/src/features/
└── evaluation/ # 评估任务执行
```
资料来源：[web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)
---
## 使用指南
### 创建评分配置
在项目中定义评分规则，确保数据一致性：
```typescript
const scoreConfig = {
projectId: "proj_xxx",
name: "relevance_score",
dataType: "NUMERIC",
description: "衡量生成内容与查询的相关程度",
valueRange: { min: 0, max: 1 }
};
```
### 使用评分分析组件
```tsx
import { ScoreAnalyticsProvider } from "@/features/score-analytics";
import { ScoreAnalyticsDashboard } from "./ScoreAnalyticsDashboard";
function ScoresPage({ projectId }) {
return (
);
}
```
---
## 性能注意事项
| 优化项 | 说明 |
|--------|------|
| **单次转换** | 所有数据转换在 Hook 中执行一次，避免重复计算 |
| **记忆化** | 所有转换函数使用 `useMemo` 进行依赖跟踪 |
| **上下文隔离** | 数据和状态通过 React Context 传递，避免 prop drilling |
| **ClickHouse 查询** | 大规模分析数据通过 ClickHouse 进行聚合计算 |
---
## 数据集管理
### 相关页面
相关主题：[评估系统](#p-evaluations), [追踪系统](#p-tracing)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/shared/src/domain/dataset-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-items.ts)
- [packages/shared/src/domain/dataset-run-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-run-items.ts)
- [packages/shared/src/server/services/DatasetService](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/services/DatasetService)
- [web/src/features/datasets](https://github.com/langfuse/langfuse/blob/main/web/src/features/datasets)
- [worker/src/features/experiments](https://github.com/langfuse/langfuse/blob/main/worker/src/features/experiments)
- [packages/shared/scripts/seeder/utils/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/scripts/seeder/utils/README.md)
- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
# 数据集管理
## 概述
数据集管理（Datasets）是 Langfuse 平台的核心功能之一，用于管理和组织用于评估和测试 LLM 应用的数据集合。数据集由多个数据项组成，每个数据项包含输入、期望输出以及其他元数据，支持在实验和评估流程中被引用和执行。
数据集管理功能覆盖了从数据项的创建、编辑，到运行时与 trace 的关联，再到实验执行和结果评估的完整生命周期。
## 核心数据模型
### DatasetItem（数据集项）
`DatasetItem` 是数据集的基本组成单元，代表数据集中的单个测试样本。
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 数据项唯一标识符 |
| `datasetId` | string | 所属数据集 ID |
| `input` | JSON | 输入数据，支持任意结构 |
| `expectedOutput` | JSON (可选) | 期望输出，用于评估 |
| `metadata` | JSON (可选) | 附加元数据信息 |
| `sourceTraceId` | string (可选) | 来源 trace ID |
| `sourceObservationId` | string (可选) | 来源 observation ID |
| `createdAt` | DateTime | 创建时间 |
| `updatedAt` | DateTime | 更新时间 |
资料来源：[packages/shared/src/domain/dataset-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-items.ts)
### DatasetRunItem（数据集运行项）
`DatasetRunItem` 记录数据集在特定实验运行中的执行结果，将数据集项与实际执行产生的 trace 关联起来。
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 运行项唯一标识符 |
| `datasetRunId` | string | 所属实验运行 ID |
| `datasetItemId` | string | 关联的数据集项 ID |
| `traceId` | string | 关联的执行 trace ID |
| `observationId` | string (可选) | 关联的 observation ID |
| `status` | enum | 执行状态：`success` / `error` / `skipped` |
| `error` | string (可选) | 错误信息 |
| `startTime` | DateTime | 开始时间 |
| `endTime` | DateTime (可选) | 结束时间 |
| `createdAt` | DateTime | 创建时间 |
资料来源：[packages/shared/src/domain/dataset-run-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-run-items.ts)
## 架构设计
### 系统架构图
```mermaid
graph TD
subgraph 前端层["前端层 (web/src/features/datasets)"]
UI[数据集管理界面]
Hooks[React Hooks]
end
subgraph 服务层["服务层 (packages/shared)"]
DS[DatasetService]
DRS[DatasetRunService]
end
subgraph 数据层["数据层"]
PG[(PostgreSQL)]
CH[(ClickHouse)]
end
subgraph 实验执行层["实验执行层 (worker/src/features/experiments)"]
Executor[实验执行器]
Evaluator[评估器]
end
UI --> Hooks
Hooks --> DS
DS --> DRS
DRS --> PG
DRS --> CH
Executor --> DRS
Executor --> Evaluator
Evaluator --> CH
```
### 服务层职责
**DatasetService** 负责数据集的核心业务逻辑：
- 创建和管理数据集
- 数据集项的 CRUD 操作
- 数据集与项目（Project）的关联管理
**DatasetRunService** 负责实验运行的生命周期：
- 管理实验运行的创建和状态
- 关联数据集项与执行 trace
- 记录执行结果和评估数据
## 实验与评估
### 实验系统概述
Langfuse 的实验系统（Experiments）与数据集管理紧密集成，支持以下核心功能：
1. **数据集选择**：从现有数据集中选择运行的数据项
2. **变量注入**：将数据集项的输入注入到 prompt 模板中
3. **批量执行**：对数据集中的所有项执行推理
4. **结果收集**：收集执行产生的 trace 和 observation
5. **评估计算**：基于预设的评分标准计算评估分数
资料来源：[worker/src/features/experiments](https://github.com/langfuse/langfuse/blob/main/worker/src/features/experiments)
### 实验运行流程
```mermaid
graph LR
A[启动实验] --> B[加载数据集项]
B --> C{遍历数据项}
C -->|存在未处理项| D[注入变量到 Prompt]
D --> E[执行 LLM 调用]
E --> F[创建 Trace]
F --> G[记录 DatasetRunItem]
G --> H{评估分数}
H --> I[计算评分]
I --> C
C -->|处理完成| J[生成实验报告]
```
### 评估数据存储
评估相关的分数数据存储在 ClickHouse 中，支持高效的查询和分析：
- 实验运行的分数数据通过 `SeederOrchestrator` 批量插入
- 支持环境（environment）过滤：`production`、`development`、`staging`
- 支持按数据集和实验运行进行聚合查询
资料来源：[packages/shared/scripts/seeder/utils/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/scripts/seeder/utils/README.md)
## API 接口
### 评分接口版本
Langfuse 为评分（Scores）功能提供了 v1 和 v2 两个 API 版本：
| 特性 | v1 API | v2 API |
|------|--------|--------|
| traceId | 必需 | 可选 |
| sessionId | 不支持 | 支持 |
| 数据集运行评分 | 支持 | 支持 |
| 适用对象 | 仅 trace 级别 | trace、session、数据集运行 |
资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
### 核心 API 端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v2/datasets` | POST | 创建数据集 |
| `/api/v2/datasets/:id/items` | POST | 添加数据集项 |
| `/api/v2/datasets/:id/items` | GET | 获取数据集项列表 |
| `/api/v2/datasets/:id/run` | POST | 创建实验运行 |
| `/api/v2/datasets/:id/run/:runId/results` | GET | 获取实验运行结果 |
## 前端组件
前端数据集管理功能位于 `web/src/features/datasets` 目录，提供以下核心功能：
- 数据集列表展示和搜索
- 数据集项的添加、编辑、删除
- 实验运行的历史记录查看
- 实验结果的可视化展示
### 数据集列表页面
数据集列表页面提供以下功能：
- 按名称、环境过滤数据集
- 查看数据集项数量
- 快速操作入口（运行实验、导出数据）
### 数据集详情页面
数据集详情页面展示：
- 数据集基本信息（名称、描述、创建时间）
- 数据集项列表（支持分页）
- 实验运行历史
- 评估分数统计
## 数据流转
```mermaid
graph TD
subgraph 数据录入
UserInput[用户录入]
Import[批量导入]
end
subgraph 数据存储
PG[(PostgreSQL
数据集元数据)]
CH[(ClickHouse
运行时数据)]
end
subgraph 评估执行
Experiment[实验]
LLM[LLM 调用]
end
subgraph 结果分析
ScoreUI[分数展示]
TraceView[Trace 详情]
end
UserInput --> PG
Import --> PG
Experiment --> LLM
LLM --> PG
LLM --> CH
Experiment --> CH
CH --> ScoreUI
PG --> TraceView
```
## 环境与隔离
### 多环境支持
数据集支持环境隔离，确保不同环境（生产、开发、测试）的数据相互独立：
- `production`：生产环境数据
- `development`：开发环境数据
- `staging`：预发布环境数据
### 数据隔离策略
| 环境 | 数据来源 | 访问权限 |
|------|----------|----------|
| production | 正式 LLM 调用 | 仅生产用户 |
| development | 测试 LLM 调用 | 开发团队 |
| staging | 预发布测试 | 测试团队 |
资料来源：[packages/shared/scripts/seeder/utils/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/scripts/seeder/utils/README.md)
## 最佳实践
### 数据集组织
1. **按用途分类**：将用于不同目的的数据集分开管理
2. **版本控制**：对重要数据集进行版本标记
3. **元数据丰富**：为数据项添加充分的元数据，便于筛选和分析
### 实验设计
1. **小规模测试**：先在小数据集上验证实验逻辑
2. **变量控制**：确保对比实验仅改变目标变量
3. **结果复现**：记录实验参数，便于复现结果
### 评估配置
1. **选择合适的评分标准**：根据业务需求选择或自定义评分函数
2. **设置合理的阈值**：避免过于宽松或严格的评估标准
3. **定期校准**：随着 LLM 版本更新，重新校准评估标准
## 相关模块
| 模块 | 位置 | 说明 |
|------|------|------|
| 数据集服务 | `packages/shared/src/server/services/DatasetService` | 后端数据集业务逻辑 |
| 数据集项领域模型 | `packages/shared/src/domain/dataset-items.ts` | 数据集项数据模型 |
| 运行项领域模型 | `packages/shared/src/domain/dataset-run-items.ts` | 实验运行项数据模型 |
| 前端功能 | `web/src/features/datasets` | 前端数据集管理界面 |
| 实验执行 | `worker/src/features/experiments` | 实验执行引擎 |
---
## 队列系统
### 相关页面
相关主题：[系统架构](#p-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/shared/src/server/redis/ingestionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/ingestionQueue.ts)
- [packages/shared/src/server/redis/evalExecutionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/evalExecutionQueue.ts)
- [packages/shared/src/server/redis/batchActionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/batchActionQueue.ts)
- [packages/shared/src/server/queues.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/queues.ts)
- [worker/src/queues](https://github.com/langfuse/langfuse/blob/main/worker/src/queues)
- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)
# 队列系统
## 概述
Langfuse 的队列系统是基于 Redis 和 BullMQ 构建的消息队列基础设施，负责处理异步任务、事件摄取、评估执行和批量操作。该系统采用生产者和消费者模式，通过队列解耦服务间的通信，提高系统的可扩展性和可靠性。
队列系统在 Langfuse 架构中扮演核心角色，主要承担以下职责：
- **事件摄取**：处理来自 SDK 和 OTEL 协议的事件数据
- **评估执行**：管理评估任务的异步执行
- **批量操作**：处理需要批量处理的后台任务
- **事件重放**：支持从 S3 重新导入历史事件
## 架构设计
Langfuse 采用多队列架构，不同类型的任务使用独立的队列，每个队列由专门的消费者处理器处理。
```mermaid
graph TD
subgraph "生产者"
SDK[Langfuse SDK]
OTEL[OTEL Protocol]
API[API Server]
end
subgraph "队列层"
IQ[IngestionQueue
摄取队列]
OIQ[OtelIngestionQueue
OTEL摄取队列]
ISQ[IngestionSecondaryQueue
摄取次级队列]
EEQ[EvalExecutionQueue
评估执行队列]
BAQ[BatchActionQueue
批量操作队列]
end
subgraph "消费者"
Worker[Worker Service]
end
SDK --> IQ
OTEL --> OIQ
API --> EEQ
API --> BAQ
IQ --> Worker
OIQ --> Worker
ISQ --> Worker
EEQ --> Worker
BAQ --> Worker
Worker --> Redis[(Redis)]
```
## 队列类型
### 摄取队列 (IngestionQueue)
摄取队列是 Langfuse 最核心的队列，负责处理来自客户端 SDK 的事件数据。事件类型包括 traces、generations、scores、evals 等。
| 属性 | 说明 |
|------|------|
| 队列名称 | `ingestion` |
| 优先级 | 高 |
| 并发处理 | 支持多worker并发消费 |
| 重试机制 | 支持指数退避重试 |
| 数据存储 | Redis |
**事件格式示例**：
```json
{
"projectId": "project-123",
"orgId": "org-456",
"eventType": "trace-create",
"body": { /* 事件数据 */ }
}
```
资料来源：[packages/shared/src/server/redis/ingestionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/ingestionQueue.ts)
### OTEL 摄取队列 (OtelIngestionQueue)
专门处理 OpenTelemetry 协议格式的事件，采用特定的文件存储路径格式。
**S3 文件路径格式**：
```
otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json
```
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)
### 摄取次级队列 (IngestionSecondaryQueue)
作为摄取队列的补充队列，用于处理需要二次处理的事件或分流部分摄取负载。
### 评估执行队列 (EvalExecutionQueue)
负责调度和管理评估任务的执行。当用户触发评估操作时，评估任务被加入此队列，由专门的评估工作器异步处理。
| 属性 | 说明 |
|------|------|
| 队列名称 | `eval-execution` |
| 优先级 | 中 |
| 任务类型 | 异步评估计算 |
| 超时处理 | 支持任务超时配置 |
资料来源：[packages/shared/src/server/redis/evalExecutionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/evalExecutionQueue.ts)
### 批量操作队列 (BatchActionQueue)
处理需要批量执行的系统操作，如批量更新、批量删除等后台任务。
| 属性 | 说明 |
|------|------|
| 队列名称 | `batch-action` |
| 优先级 | 低 |
| 批处理大小 | 可配置 |
| 事务支持 | 支持批量事务 |
资料来源：[packages/shared/src/server/redis/batchActionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/batchActionQueue.ts)
## 队列配置
Langfuse 在中央配置文件 `queues.ts` 中定义所有队列的默认配置和行为。
```typescript
// packages/shared/src/server/queues.ts 中的典型配置结构
interface QueueConfig {
name: string;
concurrency: number;
maxRetries: number;
backoff: {
type: 'exponential' | 'fixed';
delay: number;
};
removeOnComplete: boolean | number;
removeOnFail: boolean | number;
}
```
资料来源：[packages/shared/src/server/queues.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/queues.ts)
## 消费者与工作器
### Worker 服务架构
Worker 服务运行在独立的进程中，通过 Redis 连接队列并消费消息。每个队列类型对应专门的处理逻辑。
```mermaid
graph LR
subgraph "Worker 进程"
subgraph "处理器"
IQH[IngestionHandler]
OIQH[OtelHandler]
EEQH[EvalHandler]
BAH[BatchHandler]
end
subgraph "队列连接"
R[Redis BullMQ]
end
end
IQH --> R
OIQH --> R
EEQH --> R
BAH --> R
```
### 处理器职责
| 处理器 | 队列 | 主要功能 |
|--------|------|----------|
| IngestionHandler | IngestionQueue | 解析事件、存储ClickHouse、触发后续处理 |
| OtelHandler | OtelIngestionQueue | 处理OTEL格式事件、文件下载与解析 |
| EvalHandler | EvalExecutionQueue | 执行评估计算、存储评估结果 |
| BatchHandler | BatchActionQueue | 执行批量数据库操作 |
资料来源：[worker/src/queues](https://github.com/langfuse/langfuse/blob/main/worker/src/queues)
## 事件重放系统
Langfuse 提供了事件重放脚本，允许从 S3 重新导入历史事件到队列系统。
### replayIngestionEventsV2
最新版本的事件重放工具，提供完整的事件重放功能。
**主要特性**：
- 支持从 S3 读取历史事件
- 支持增量重放和断点续传
- 内置速率限制和重试机制
- 支持批量并发请求
**命令行参数**：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--input` | - | CSV文件路径 |
| `--batch-size` | 500 | 每次API请求的key数量 |
| `--concurrency` | 4 | 最大并发API请求数 |
| `--rate-limit` | 50 | 每秒最大请求数 |
| `--dry-run` | false | 仅解析验证，不发送请求 |
| `--resume` | false | 从上次断点继续 |
**环境变量**：
| 变量 | 说明 |
|------|------|
| `LANGFUSE_HOST` | 目标Langfuse实例URL |
| `ADMIN_API_KEY` | 管理员API认证密钥 |
**进度追踪与错误处理**：
- **进度日志**：每批次处理后记录进度（如 `[1200/45000] 2.7% — 498 queued, 2 skipped`）
- **检查点**：每批成功处理后写入检查点文件到CSV同目录，使用 `--resume` 可从断点继续
- **速率限制**：尊重本地 `--rate-limit` 配置，对429响应使用指数退避
- **重试机制**：临时错误（429、5xx）最多重试3次，永久错误（其他4xx）记录并跳过
- **错误日志**：失败记录追加到输入文件同目录的 `errors.csv`
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)
### v1 与 v2 版本对比
| 特性 | v1 | v2 |
|------|----|----|
| 基础设施访问 | Redis、ClickHouse、PostgreSQL、S3 | 仅需Langfuse Host URL |
| 配置复杂度 | 需完整repo克隆和环境配置 | 只需 tsx 运行 + 环境变量 |
| 事件投递 | 直接BullMQ addBulk到Redis | HTTP POST到管理API |
| 断点续传 | 手动（分割文件、重跑） | 内置检查点/续传 |
| 速率限制 | 无（可能压垮Redis） | 客户端+服务端双重限速 |
## 事件转换
重放脚本支持两种 S3 key 格式的转换：
### 标准格式
路径：`{projectId}/{type}/{eventBodyId}/{eventId}.json`
转换结果：
```json
{
"authCheck": {
"validKey": true,
"scope": { "projectId": "" }
},
"data": {
"eventBodyId": "",
"fileKey": "",
"type": "-create"
}
}
```
投递到 `IngestionSecondaryQueue`。
### OTEL 格式
路径：`otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json`
转换结果：
```json
{
"authCheck": {
"validKey": true,
"scope": { "projectId": "", "accessLevel": "project" }
},
"data": {
"fileKey": "otel///////.json"
}
}
```
投递到 `OtelIngestionQueue`。
## 管理员 API 端点
### POST /api/admin/ingestion-replay
接受批量 S3 key 并将其排队等待重新处理。
**认证方式**：`Authorization: Bearer {ADMIN_API_KEY}` 头，由 `AdminApiAuthService` 验证。
**请求格式**：
```json
{
"keys": [
"projectId/trace/eventBodyId/eventId.json",
"otel/projectId/2025/07/09/14/30/some-uuid.json"
]
}
```
**响应格式**：
```json
{
"queued": 498,
"skipped": 2,
"errors": []
}
```
**状态码说明**：
| 状态码 | 含义 |
|--------|------|
| 200 | 批次已接受（检查 `skipped`/`errors` 了解部分失败） |
| 401 | 缺少或无效的 `ADMIN_API_KEY` |
| 400 | 请求体格式错误 |
| 429 | 速率限制，等待退避后重试 |
## 性能优化
队列系统采用多种策略确保高性能：
### 并发处理
- 不同队列可独立配置并发数
- Worker 支持水平扩展，多实例并行消费
- 基于 Redis 的队列提供低延迟的消息传递
### 重试机制
```mermaid
graph TD
A[消息处理失败] --> B{错误类型}
B -->|临时错误 429/5xx| C[指数退避重试]
B -->|永久错误 4xx| D[记录并跳过]
C --> E[重试次数 < 3?]
E -->|是| A
E -->|否| D
```
### 资源管理
- 完成或失败的消息自动清理（可配置保留策略）
- 死信队列处理长时间失败的消息
- 内存敏感操作使用流式处理
## 监控与调试
### 本地调试工具
事件重放脚本提供进度追踪功能：
```bash
# 运行脚本会输出类似：
[1200/45000] 2.7% — 498 queued, 2 skipped
```
### 检查点文件
脚本在每次批量处理成功后保存检查点：
```
./worker/events.csv
./worker/events.csv.checkpoint # 存储当前行偏移量
```
### 错误日志
处理失败的事件记录到 `errors.csv`：
```csv
s3_key,error_message,timestamp
projectId/trace/xxx.json,Rate limited,2025-07-09T10:30:00Z
```
## 最佳实践
### 生产环境部署
1. **队列隔离**：不同环境的队列使用不同的 Redis 实例或键前缀
2. **监控告警**：配置队列深度、处理延迟、失败率的监控
3. **优雅关闭**：Worker 支持优雅关闭，确保处理中的任务完成
### 故障恢复
1. **启用检查点**：长时间运行的批量任务使用断点续传
2. **死信处理**：定期检查死信队列，分析失败原因
3. **数据校验**：重放前验证事件格式，避免格式错误导致处理失败
### 容量规划
- 根据峰值吞吐量配置 Worker 并发数
- 监控队列积压情况，动态扩展 Worker
- 评估 Redis 内存使用，预留足够空间
## 相关文档
- [Worker 服务文档](../worker/README.md)
- [事件摄取系统](./ingestion.md)
- [评估执行系统](./evaluation.md)
- [ClickHouse 存储](./clickhouse.md)
---
## API 系统
### 相关页面
相关主题：[追踪系统](#p-tracing)
相关源码文件
以下源码文件用于生成本页说明：
- [fern/apis/server/definition](https://github.com/langfuse/langfuse/blob/main/fern/apis/server/definition)
- [fern/apis/client/definition](https://github.com/langfuse/langfuse/blob/main/fern/apis/client/definition)
- [packages/shared/src/server/ingestion](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/ingestion)
- [web/src/features/public-api](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api)
- [packages/shared/src/features/scores/interfaces](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces)
- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)
# API 系统
## 概述
Langfuse 的 API 系统是一个多层架构，支持数据摄取、公共 API 接口、客户端 SDK 以及服务端内部调用。该系统采用 Fern 进行 API 定义和类型生成，实现了服务端和客户端的双向代码生成，确保 API 的一致性和类型安全。
API 系统主要包含以下几个核心组成部分：
- **摄取 API (Ingestion API)**：接收来自 SDK 和集成工具的事件数据
- **公共 API (Public API)**：面向外部开发者的高层 REST 接口
- **客户端 SDK API**：Python 和 JavaScript/TypeScript SDK 使用的接口
- **服务端定义 API**：内部服务端使用的 API 定义
资料来源：[web/src/features/public-api/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api/README.md)
---
## 架构设计
### 整体架构图
```mermaid
graph TD
subgraph 外部客户端
A[Python SDK]
B[JS/TS SDK]
C[直接 HTTP 请求]
end
subgraph API 层
D[摄取 API]
E[公共 API]
F[Admin API]
end
subgraph 服务端组件
G[Next.js API Routes]
H[BullMQ Queues]
I[Prisma ORM]
end
subgraph 数据存储
J[(PostgreSQL)]
K[(ClickHouse)]
L[(Redis)]
end
A --> D
B --> D
C --> D
C --> E
D --> H
H --> I
I --> J
I --> K
I --> L
E --> G
G --> I
```
### API 版本策略
Langfuse 采用双版本 API 策略，同时维护 v1 和 v2 两个版本的 API：
| 版本 | 状态 | 说明 |
|------|------|------|
| v1 | 继续支持 | 遗留 API，聚焦于 trace 级别 |
| v2 | 当前版本 | 支持 traces、sessions 及更多功能 |
**关键差异**：在 GET API 中，v1 需要 `traceId` 参数且仅支持 trace 级别分数；v2 将 `traceId` 设为可选，并新增 `sessionId` 支持。
资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
---
## 摄取 API (Ingestion API)
### 功能概述
摄取 API 是 Langfuse 数据入口点，负责接收来自各类 SDK 和集成工具的事件数据，包括 traces、generations、spans、events 等。
### 支持的事件类型
摄取 API 支持多种事件类型的批量摄取：
```typescript
// 标准事件结构
interface IngestionEvent {
eventBodyId: string; // 事件体 ID
type: EventType; // 事件类型
timestamp: Date; // 事件时间戳
metadata?: Record;
}
```
### S3 事件回放
对于大规模事件重放场景，Langfuse 提供了基于 S3 的事件回放功能：
```mermaid
graph LR
A[S3 Access Logs] --> B[CSV 文件]
B --> C[replayIngestionEventsV2]
C --> D{批量处理}
D -->|500 条/批| E[POST /api/admin/ingestion-replay]
E --> F[摄取队列]
F --> G[ClickHouse/PostgreSQL]
```
### 回放脚本参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--csv` | 必需 | CSV 文件路径 |
| `--batch-size` | 500 | 每批 API 请求的键数量 |
| `--concurrency` | 4 | 最大并行 API 请求数 |
| `--rate-limit` | 50 | 最大每秒请求数 |
| `--dry-run` | false | 仅解析验证不发送 |
| `--resume` | false | 从上次检查点继续 |
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)
---
## 公共 API (Public API)
### 路由创建规范
Langfuse 的公共 API 路由遵循严格的实现规范：
```typescript
// 标准 API 路由结构
import { withMiddleware } from "@/src/apiMiddleware";
import { createAuthedAPIRoute } from "@/src/lib/createAuthedAPIRoute";
// 使用 withMiddleware 包装
export default withMiddleware(
createAuthedAPIRoute({
// Zod 类型定义
request: z.object({...}),
response: z.object({...}),
// 业务逻辑
handler: async (req, res) => {
// 实现代码
}
})
);
```
### 类型定义位置
所有公共 API 的类型定义位于 `packages/shared/src/features/public-api/types/` 目录：
- 使用 `coerce` 处理日期等原始类型转换
- 对不应返回额外属性的对象使用 `strict()` 模式
- 使用 `validateZodSchema` 在 API 路由中验证响应类型
### API 响应验证
```typescript
import { validateZodSchema } from "@/src/lib/validateZodSchema";
// 在 API 路由中验证响应
const validatedResponse = validateZodSchema(response, ResponseSchema);
```
### 错误处理
公共 API 使用 `shared/src/errors` 中定义的错误类，这些错误会自动转换为相应的 HTTP 状态码：
```typescript
import { ValidationError, NotFoundError } from "@/src/errors";
// 抛出错误会被自动转换
throw new ValidationError("Invalid input");
throw new NotFoundError("Resource not found");
```
资料来源：[web/src/features/public-api/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api/README.md)
---
## Fern API 定义
### 概述
Langfuse 使用 Fern 进行 API 定义，实现服务端和客户端的代码生成。
### 目录结构
```
fern/
├── apis/
│ ├── server/
│ │ └── definition/ # 服务端 API 定义
│ └── client/
│ └── definition/ # 客户端 SDK API 定义
```
### 代码生成流程
```mermaid
graph TD
A[Fern 定义文件] --> B[fern generate --api server]
A --> C[fern generate --api client]
B --> D[服务端类型]
C --> E[Python SDK 类型]
C --> F[JS/TS SDK 类型]
```
### 生成命令
```bash
# 生成服务端 API
fern generate --api server
# 生成客户端 API
fern generate --api client
# 提交生成的变更
git commit -m "chore: update api reference"
```
### API Reference 文档
生成的 API Reference 会被添加到 Fern 文档中，包含 `docs` 属性用于描述接口用途和参数说明。
资料来源：[web/src/features/public-api/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api/README.md)
---
## 分数接口 (Score Interfaces)
### 目录结构
```
packages/shared/src/features/scores/interfaces/
├── api/
│ ├── v1/ # v1 API 类型
│ │ ├── endpoints.ts
│ │ ├── schemas.ts
│ │ └── validation.ts
│ ├── v2/ # v2 API 类型
│ │ ├── endpoints.ts
│ │ ├── schemas.ts
│ │ └── validation.ts
│ └── shared.ts # 通用类型
├── application/ # 应用层验证
│ └── validation.ts
├── ingestion/ # 摄取端点类型
│ └── validation.ts
└── ui/ # UI 组件类型
└── types.ts
```
### API 版本对比
| 特性 | v1 API | v2 API |
|------|--------|--------|
| traceId 参数 | 必需 | 可选 |
| sessionId 支持 | ❌ | ✅ |
| 支持的分数类型 | trace 级别 | trace、session、dataset run |
### 验证层次
分数接口采用多层验证架构：
1. **API 层验证** (`api/v1/validation.ts`, `api/v2/validation.ts`)：处理请求参数验证
2. **应用层验证** (`application/validation.ts`)：业务逻辑验证
3. **摄取层验证** (`ingestion/validation.ts`)：数据摄取时的验证
资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)
---
## Admin API
### 认证机制
Admin API 使用 `Authorization: Bearer {ADMIN_API_KEY}` 头部进行认证：
```bash
curl -X POST https://your-langfuse.com/api/admin/ingestion-replay \
-H "Authorization: Bearer $ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keys": ["projectId/trace/eventBodyId/eventId.json"]}'
```
### 端点：摄取回放
**端点**：`POST /api/admin/ingestion-replay`
**请求格式**：
```json
{
"keys": [
"projectId/trace/eventBodyId/eventId.json",
"otel/projectId/2025/07/09/14/30/some-uuid.json"
]
}
```
**响应格式**：
```json
{
"queued": 498,
"skipped": 2,
"errors": []
}
```
### 响应状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 批量已接受（检查 `skipped`/`errors` 获取部分失败信息） |
| 401 | 缺少或无效的 `ADMIN_API_KEY` |
| 400 | 请求体格式错误 |
| 429 | 速率限制，请稍后重试 |
### 事件转换
**标准键格式**：`{projectId}/{type}/{eventBodyId}/{eventId}.json`
转换后的队列负载：
```json
{
"authCheck": {
"validKey": true,
"scope": { "projectId": "" }
},
"data": {
"eventBodyId": "",
"fileKey": "",
"type": "-create"
}
}
```
**OTEL 键格式**：`otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json`
资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)
---
## SDK API
### Python SDK
Python SDK 使用从 Fern 生成的类型和接口，提供与 Langfuse 服务器交互的便捷方法：
```python
from langfuse import Langfuse
client = Langfuse(
public_key="pk-lf-xxx",
secret_key="sk-lf-xxx",
host="https://cloud.langfuse.com"
)
# 创建 trace
trace = client.trace.create(
name="my-trace",
metadata={"user_id": "123"}
)
```
### JavaScript/TypeScript SDK
JS/TS SDK 采用相同的 Fern 定义，确保与 Python SDK 行为一致：
```typescript
import { Langfuse } from "langfuse-js";
const langfuse = new Langfuse({
publicKey: "pk-lf-xxx",
secretKey: "sk-lf-xxx",
baseUrl: "https://cloud.langfuse.com"
});
// 创建 trace
const trace = await langfuse.trace.create({
name: "my-trace",
metadata: { userId: "123" }
});
```
---
## 认证与授权
### 认证方式
Langfuse API 支持多种认证方式：
| 认证方式 | 适用场景 | 说明 |
|----------|----------|------|
| API Keys | SDK 和直接调用 | public_key + secret_key |
| Basic Auth | MCP Server | base64(publicKey:secretKey) |
| Bearer Token | Admin API | ADMIN_API_KEY |
### Basic Auth 编码
```bash
# 生成 Basic Auth Token
echo -n "pk-lf-your-public-key:sk-lf-your-secret-key" | base64
```
### MCP Server 认证
MCP Server 使用 Basic Auth 认证：
```typescript
{
auth: {
authType: "BasicAuth",
accessLevel: "project",
publicKey: "pk-lf-..."
}
}
```
资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)
---
## 测试策略
### API 响应验证测试
使用 `makeZodVerifiedAPICall` 测试工具验证 API 响应：
```typescript
import { makeZodVerifiedAPICall } from "@/test/server";
it("should return correct response structure", async () => {
const response = await makeZodVerifiedAPICall(
"GET",
"/api/public-api/endpoint",
{},
ResponseSchema
);
expect(response.data).toBeDefined();
});
```
### 测试覆盖要求
- 所有标准用例必须有测试覆盖
- 使用 `strict()` 模式的对象响应，测试工具会在额外属性时抛出错误
- 生产环境会记录响应包含额外属性的错误
---
## 最佳实践
### API 路由开发流程
1. 在 `features/public-api/types/` 中添加 Zod 类型定义
2. 使用 `coerce` 处理日期等需要转换的类型
3. 在 API 路由中使用 `validateZodSchema` 验证响应
4. 添加完整的测试用例
5. 运行 `fern generate` 更新 SDK 类型
6. 提交所有变更
### 错误处理规范
- 优先使用 `shared/src/errors` 中预定义的错误类
- 避免直接返回原始错误信息给客户端
- 在生产环境记录详细的错误日志
### 性能考虑
- 批量摄取事件以减少网络开销
- 使用检查点机制支持长时间运行的批处理任务
- 实施客户端和服务器端速率限制
---
## 相关链接
- [Fern 文档](https://buildwithfern.com/)
- [Zod 验证库](https://zod.dev/)
- [Langfuse SDK 文档](https://langfuse.com/docs/sdk)
---
---
## Doramagic 踩坑日志
项目：langfuse/langfuse
摘要：发现 17 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：bug: Using client with context manager breaks the scoring。
## 1. 安装坑 · 来源证据：bug: Using client with context manager breaks the scoring
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Using client with context manager breaks the scoring
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5afee24537ba47369cc4621f7fb18122 | https://github.com/langfuse/langfuse/issues/8138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：bug: unnamed trace name in Langfuse UI
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: unnamed trace name in Langfuse UI
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a219c99fe99c4b7dab002e2b3a6296c2 | https://github.com/langfuse/langfuse/issues/13416 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 3. 安全/权限坑 · 来源证据：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8657d86702904e90b9d448770e618256 | https://github.com/langfuse/langfuse/issues/8173 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 安全/权限坑 · 来源证据：bug: Worker shutdown takes ~1 hour in self hosted kubernetes
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: Worker shutdown takes ~1 hour in self hosted kubernetes
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cff1b1d1a1ca4eb892563c33d3aa62e9 | https://github.com/langfuse/langfuse/issues/8156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_49a69075a1c346789a28db93c9ec6f3f | https://github.com/langfuse/langfuse/issues/13601 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 6. 安装坑 · 来源证据：v3.169.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.169.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_864f213fd7694eba9a4d2fe2bb9267ab | https://github.com/langfuse/langfuse/releases/tag/v3.169.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 7. 安装坑 · 来源证据：v3.172.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.172.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_14588986ba9945eeb40cbc0508e3fed0 | https://github.com/langfuse/langfuse/releases/tag/v3.172.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 8. 安装坑 · 来源证据：v3.173.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.173.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7560a954846b4f35aedb74de1291c9a4 | https://github.com/langfuse/langfuse/releases/tag/v3.173.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 9. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:642497346 | https://github.com/langfuse/langfuse | README/documentation is current enough for a first validation pass.
## 10. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | last_activity_observed missing
## 11. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium
## 12. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium
## 13. 安全/权限坑 · 来源证据：v3.168.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.168.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_202b4e8c2c1f4b3790315098d1530297 | https://github.com/langfuse/langfuse/releases/tag/v3.168.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 14. 安全/权限坑 · 来源证据：v3.170.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.170.0
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9ed6f994e1424878aa4559a73d72fc52 | https://github.com/langfuse/langfuse/releases/tag/v3.170.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 15. 安全/权限坑 · 来源证据：v3.174.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.174.0
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f9cb7b7232ff4cce96f0c020fe48c7f4 | https://github.com/langfuse/langfuse/releases/tag/v3.174.0 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 16. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | issue_or_pr_quality=unknown
## 17. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | release_recency=unknown