# 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-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# langx-example

LangChain + LangGraph + LangFuse 学习项目，面向具备 Java/Spring 背景的 LLM 应用开发者。
通过三个递进模块（核心层 → 编排层 → 观测层）贯穿 RAG 问答、Agent 工具调用、工作流自动化三个场景，逐步掌握 LLM 应用开发与可观测性。

- **模块① 核心层** `src/langx/` — LLM 调用、RAG 检索、Prompt 管理、工具定义（类比 Spring Framework）
- **模块② 编排层** `src/langx/graph/` — LangGraph 状态机构建与条件路由（类比 Spring State Machine）
- **模块③ 观测层** `src/langx/observe/` — LangFuse Trace 可观测性埋点（类比 Spring Actuator + Sleuth）

## 框架类比

以下映射帮助 Java/Spring 开发者快速定位 LangChain 生态中的对应概念（类比旨在帮助理解，不完全一一对应）：

| Java/Spring 生态 | LangChain 生态 | 本项目选用 |
|---|---|---|
| Spring Framework（核心抽象、DI） | LangChain Core（Runnable、PromptTemplate） | ✓ |
| Spring Data / JDBC（数据访问） | LangChain 集成包（OpenAI、PGVector） | ✓ |
| Spring State Machine（状态机编排） | LangGraph（StateGraph + 条件路由） | ✓ |
| Spring Actuator + Sleuth（可观测性） | LangSmith（商业 SaaS，**不开源**） | ✗ |
| | LangFuse（开源，Docker 自部署） | ✓ 替代选用 |

> **生态说明**：LangChain 与 LangGraph 同属 [LangChain AI](https://github.com/langchain-ai) 组织。LangFuse 由独立组织维护，作为 LangSmith 的开源替代方案提供自部署的可观测性能力。

## 项目结构

```
langx-example/
├── src/
│   ├── langx/                     # 核心层：LLM 调用、RAG 检索、Prompt 管理、工具定义
│   │   ├── __init__.py
│   │   ├── config.py              # 配置管理（单例 + 环境变量）
│   │   ├── llm.py                 # LLM 调用封装（ChatOpenAI）
│   │   ├── prompt.py              # Prompt 模板中心
│   │   ├── tools.py               # 工具定义（天气 / 计算器）
│   │   ├── rag.py                 # RAG 检索（PGVector + Embedding）
│   │   ├── graph/                 # 编排层：LangGraph 状态机
│   │   │   ├── graph_rag.py
│   │   │   ├── graph_agent.py
│   │   │   └── graph_workflow.py
│   │   └── observe/               # 观测层：LangFuse Trace
│   │       ├── chain.py
│   │       └── graph.py
│   └── demos/                     # 统一入口：三种场景
│       ├── agent.py
│       ├── rag.py
│       └── workflow.py
├── .env.example                   # 环境变量模板
├── .gitignore
├── pyproject.toml                 # 单包配置（hatchling）
├── uv.lock
├── langfuse-docker-deploy/        # LangFuse v3 Docker 部署
└── openspec/                      # OpenSpec 工作流元数据
```

## 前置依赖

- Python >= 3.11
- [uv](https://github.com/astral-sh/uv) 包管理器
- PostgreSQL 实例（含 pgvector 扩展）
- Docker（仅用于部署 LangFuse 服务端）
- sentence-transformers 模型（用于 RAG 中文档向量化，首次运行自动下载 all-MiniLM-L6-v2）

## 快速开始

### 1. 安装依赖

```bash
uv sync
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 然后编辑 .env，填入 API Key 和数据库信息
```

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

### 3. 部署 LangFuse 服务端

**本地开发：**

```bash
cd langfuse-docker-deploy
cp .env.example .env
# 编辑 .env 填入密钥和管理员账号
docker compose up -d
```

**生产部署：** 将 `langfuse-docker-deploy/` 目录传到服务器，编辑 `.env` 后执行：

```bash
sudo ./deploy.sh
```

详细部署说明见 [`langfuse-docker-deploy/README.md`](langfuse-docker-deploy/README.md)。

### 4. 初始化 pgvector 扩展

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

## 运行示例

```bash
# Agent Demo
uv run python -m src.demos.agent

# RAG Demo
uv run python -m src.demos.rag

# Workflow Demo
uv run python -m src.demos.workflow
```

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

## 依赖关系

```
src/demos/          ──→   src/langx/        (核心能力：LLM / RAG / Tool)
                  ──→   src/langx/graph/   (编排层：状态机构建)

src/langx/observe/   ──  横切关注点 —— 通过 Callback 贯穿所有调用链路
```

## License

MIT