# langx-example

**Repository Path**: bytesifter/langx-example

## Basic Information

- **Project Name**: langx-example
- **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-15
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# langx-example

LangChain + LangGraph + LangFuse 学习项目。通过三个递进模块和一个贯穿三个场景（RAG 问答、Agent 工具调用、工作流自动化）的示例，逐步掌握 LLM 应用开发与可观测性。

## 项目结构

```
langx-example/
├── pyproject.toml                  # uv workspace 根配置
├── .env.example                    # 环境变量模板
├── projects/
│   ├── langchain-example/          # 基础组件：LLM、Prompt、RAG、Tool
│   ├── langgraph-example/          # 状态机编排：复用 langchain 组件
│   └── langfuse-example/           # 可观测性：Trace/Cost/Eval
└── openspec/                       # OpenSpec 工作流元数据
```

## 前置依赖

- Python >= 3.11
- [uv](https://github.com/astral-sh/uv) 包管理器
- PostgreSQL 实例（含 pgvector 扩展）
- Docker（仅用于部署 LangFuse 服务端）

## 快速开始

### 1. 安装依赖

```bash
uv sync
```

### 2. 配置环境变量

复制并编辑 `.env.example` 为 `.env`：

```bash
cp .env.example .env
```

`.env` 说明：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OPENAI_API_KEY` | LLM API Key (OpenAI 兼容) | — |
| `OPENAI_BASE_URL` | LLM 端点 | `https://api.openai.com/v1` |
| `OPENAI_MODEL` | 模型名 | `gpt-4o` |
| `DB_HOST` | PostgreSQL 地址 | `192.168.56.120` |
| `DB_PORT` | PostgreSQL 端口 | `5432` |
| `DB_USER` | PostgreSQL 用户 | `langxrag` |
| `DB_PASSWORD` | PostgreSQL 密码 | `123456` |
| `DB_NAME` | 数据库名 | `langxrag` |
| `LANGFUSE_HOST` | LangFuse 服务地址 | `http://localhost:3000` |
| `LANGFUSE_PUBLIC_KEY` | LangFuse 公钥 | — |
| `LANGFUSE_SECRET_KEY` | LangFuse 密钥 | — |

> 支持 Ollama 等兼容 OpenAI 协议的本地模型：修改 `OPENAI_BASE_URL` 和 `OPENAI_MODEL` 即可。

### 3. 部署 LangFuse 服务端

使用 Docker 部署 LangFuse 服务端（需要先有一个可用的 PostgreSQL 实例）：

```bash
# 1. 在 PG 中创建 langfuse 数据库
psql -h 192.168.56.120 -U langx -c "CREATE DATABASE langfuse;"

# 2. 生成安全密钥
NEXTAUTH_SECRET=$(openssl rand -hex 32)
SALT=$(openssl rand -hex 32)

# 3. 启动 LangFuse
docker run -d -p 3000:3000 \
  -e DATABASE_URL=postgresql://langx:123456@192.168.56.120:5432/langfuse \
  -e NEXTAUTH_SECRET=$NEXTAUTH_SECRET \
  -e SALT=$SALT \
  ghcr.io/langfuse/langfuse:latest
```

部署后访问 `http://localhost:3000` 注册账号，创建 API Key 并填入 `.env` 的 `LANGFUSE_PUBLIC_KEY` 和 `LANGFUSE_SECRET_KEY`。

### 4. 初始化 pgvector 扩展

```sql
-- 在目标数据库上启用向量扩展
CREATE EXTENSION IF NOT EXISTS vector;
```

## 运行示例

### langchain-example（基础组件）

```bash
uv run -p langchain-example python -m langchain_example.rag_demo
uv run -p langchain-example python -m langchain_example.agent_demo
uv run -p langchain-example python -m langchain_example.workflow_demo
```

### langgraph-example（状态机编排）

```bash
uv run -p langgraph-example python -m langgraph_example.rag_demo
uv run -p langgraph-example python -m langgraph_example.agent_demo
uv run -p langgraph-example python -m langgraph_example.workflow_demo
```

### langfuse-example（可观测性）

```bash
# 确保 LangFuse 服务端已运行
uv run -p langfuse-example python -m langfuse_example.rag_demo
uv run -p langfuse-example python -m langfuse_example.agent_demo
uv run -p langfuse-example python -m langfuse_example.workflow_demo
```

运行后登录 LangFuse UI (`http://localhost:3000`) 即可查看 Trace 详情。

## 依赖关系

```
langgraph-example ──depends on──▶ langchain-example
langfuse-example  ──depends on──▶ langchain-example + langgraph-example
```

## License

MIT