# langfuse-test

**Repository Path**: bingofhy/langfuse-test

## Basic Information

- **Project Name**: langfuse-test
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Langfuse 本地部署快速指南

## 🎯 5分钟快速部署

### 方法一：官方 Docker Compose（推荐）

```bash
# 1. 克隆官方仓库
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# 2. 启动服务
docker compose up -d

# 3. 等待服务启动（约2-3分钟）
docker compose ps

# 4. 访问 Web UI
# 浏览器打开: http://localhost:3000
```

**就这么简单！** 🎉

### 首次设置

1. 创建管理员账号
2. 创建第一个项目
3. 获取 API Keys
4. 开始集成

## 🐍 Python 集成示例

### 安装依赖

```bash
pip install langfuse langchain-openai langchain-core
```

### 基础使用

```python
from langfuse import Langfuse

# 初始化（使用默认测试keys）
langfuse = Langfuse(
    public_key="pk-lf-84a1defb-3a1c-4570-8daa-1878853a4075",  # 从UI获取
    secret_key="sk-lf-265c5089-9062-454a-92d5-41d935ef5ba2",  # 从UI获取
    base_url="http://localhost:3000"
)

# 创建追踪
trace = langfuse.trace(
    name="my-first-trace",
    input={"prompt": "Hello, Langfuse!"},
    metadata={"environment": "local"}
)

trace.end(output={"response": "Hello! How can I help you?"})

print(f"Trace URL: {langfuse.get_trace_url(trace.trace_id)}")
```

### LangChain 集成

```python
from langfuse.callback import CallbackHandler
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# 初始化 handler（使用默认配置）
langfuse_handler = CallbackHandler(
    public_key="pk-lf-84a1defb-3a1c-4570-8daa-1878853a4075",
    secret_key="sk-lf-265c5089-9062-454a-92d5-41d935ef5ba2",
    host="http://localhost:3000"
)

# 创建链
llm = ChatOpenAI(model_name="gpt-3.5-turbo")
prompt = ChatPromptTemplate.from_template("Tell me a joke about {topic}")
chain = prompt | llm

# 执行并自动追踪
response = chain.invoke(
    {"topic": "AI"},
    config={"callbacks": [langfuse_handler]}
)

print(response.content)
# 访问 http://localhost:3000 查看详细追踪
```

## 📊 查看数据

### Web 界面导航

1. **Traces（追踪）** - 查看所有执行记录
2. **Observations（观察）** - 详细的执行步骤
3. **Scores（评分）** - 性能评估指标
4. **Datasets（数据集）** - 测试数据管理

### 数据库查询

```bash
# ClickHouse 查询
docker exec langfuse-clickhouse-1 clickhouse-client \
  --user clickhouse --password clickhouse \
  --query "SELECT COUNT(*) as total_traces FROM traces"

# PostgreSQL 查询
docker exec langfuse-postgres-1 psql -U postgres -c \
  "SELECT COUNT(*) FROM \"Account\";"
```

## 🛠️ 常用命令

```bash
# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 查看日志
docker compose logs -f langfuse-web

# 重启服务
docker compose restart

# 查看状态
docker compose ps
```

## 📝 测试验证

### 快速测试脚本

运行基础测试：

```bash
# 激活虚拟环境
source venv/bin/activate

# 运行基础SDK测试
python test_langfuse_simple.py
```

或者运行LangGraph集成测试：

```bash
# 需要设置OpenAI API Key
OPENAI_API_KEY=your-key python test_langfuse_langgraph.py
```

## 🚨 故障排除

### 问题：服务无法启动

```bash
# 检查端口占用
lsof -i :3000

# 查看错误日志
docker compose logs langfuse-web
```

### 问题：无法访问 Web UI

```bash
# 检查容器状态
docker compose ps

# 重启 web 服务
docker compose restart langfuse-web
```

### 问题：数据未显示

```bash
# 检查 worker 日志
docker compose logs langfuse-worker | tail -50

# 等待数据处理（worker 是异步的）
sleep 30
```

## 📚 更多文档

详细文档请参考：
- [CLAUDE.md](./CLAUDE.md) - 项目架构和开发指南
- [LOCATION.md](./LOCATION.md) - 部署位置说明
- [DEPLOYMENT_REPORT.md](./DEPLOYMENT_REPORT.md) - 详细部署报告
- [TEST_RESULTS.md](./TEST_RESULTS.md) - 测试验证报告
- [Langfuse 官方文档](https://langfuse.com/docs)

## 💡 提示

1. **首次部署**建议使用默认配置
2. **生产环境**请修改所有默认密码
3. **性能优化**根据负载调整资源限制
4. **数据备份**定期备份重要数据

开始使用 Langfuse，享受 LLM 应用的完整可观测性！ 🚀