# python智能体

**Repository Path**: lejiyou/python-intelligent-agent

## Basic Information

- **Project Name**: python智能体
- **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-04-01
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 乐际游旅游智能体 — 完整搭建指南

> **技术栈**: LangGraph + LlamaIndex + FastAPI + vLLM + PostgreSQL/pgvector

---

## 整体架构

```
微信小程序 / HBuilder (uni-app)
        │  wx.request / EventSource
        ▼
┌────────────────────────────────┐
│  Java Spring Boot  :8081       │  ← 已有后端
│  AgentController               │
│  POST /agent/chat              │
│  GET  /agent/chat/stream       │
└──────────────┬─────────────────┘
               │ HTTP
               ▼
┌──────────────────────────────────────────────┐
│   Python FastAPI  :8000   ← 本文实现          │
│                                              │
│  POST /api/agent/chat                        │
│  POST /api/agent/score                       │
│  POST /api/agent/index/build                 │
│                                              │
│  ┌────────────── LangGraph ────────────────┐ │
│  │ START → classify_intent                 │ │
│  │           ↓                             │ │
│  │  ┌─────────────┬──────────────┐         │ │
│  │  retrieve_ctx  execute_tools  │         │ │
│  │  └─LlamaIndex─┘──PG Tools────┘         │ │
│  │           ↓                             │ │
│  │     generate_response ← vLLM            │ │
│  │           ↓                             │ │
│  │          END                            │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────-┘
          │                    │
          ▼                    ▼
  ┌──────────────┐    ┌────────────────────┐
  │  vLLM :8001  │    │ PostgreSQL :5432    │
  │Qwen2.5-7B    │    │ lejiyou_rag        │
  └──────────────┘    │ ├─ scenic          │
                      │ ├─ hotel           │
                      │ ├─ tour_route      │
                      │ ├─ vr_scenic       │
                      │ ├─ scenic_vectors  │ ← pgvector
                      │ ├─ hotel_vectors   │ ← pgvector
                      │ ├─ rlhf_feedback   │
                      │ └─ chat_history    │
                      └────────────────────┘
```

---

## 目录结构

```
ai_agent/
├── main.py                       # FastAPI 应用入口
├── config.py                     # 配置（pydantic-settings，读取 .env）
├── session_store.py              # 会话历史（Redis 优先 / 内存降级）
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env                          # 本地开发环境变量
├── .env.example                  # 环境变量模板
│
├── agent/
│   ├── state.py                  # AgentState TypedDict
│   ├── tools.py                  # 业务工具（景区/酒店/路线/天气查询）
│   ├── nodes.py                  # LangGraph 节点（意图/检索/工具/生成）
│   └── graph.py                  # LangGraph 工作流 + TourismAgent 封装
│
├── rag/
│   ├── embeddings.py             # 嵌入模型（BAAI/bge-m3）
│   ├── indexer.py                # 从 PostgreSQL 构建 pgvector 索引
│   └── retriever.py              # 向量相似度检索
│
├── models/
│   └── schemas.py                # Pydantic 请求/响应模型
│
├── observability/
│   └── langfuse_client.py        # Langfuse 追踪（可选）
│
└── scripts/
    ├── setup_pgvector.sql        # ★ 在 lejiyou_rag 上启用 pgvector（必须先执行）
    ├── init_local_pg.sql         # 本地 PostgreSQL 初始化（备用）
    └── init_business_tables.sql  # 业务支撑表（备用）
```

---

## 搭建步骤

### 前置检查

| 条件 | 说明 |
|------|------|
| PostgreSQL `lejiyou_rag` | ✅ 已在 115.191.40.53:5432 |
| pgvector 扩展 | 服务器已安装，脚本中执行 `CREATE EXTENSION` |
| Redis | 已在 115.191.40.53:6379 |
| Java 后端 | 已运行在 :8081，`agent.service.url=http://localhost:8000` |
| vLLM | 需要部署（见步骤2） |
| Python 3.11+ | 本机或服务器 |

---

### 步骤 1 — 初始化 pgvector 向量表

在 Navicat 或 psql 中连接 `lejiyou_rag`，执行：

```sql
-- 方式A：Navicat 打开查询窗口，复制粘贴执行
-- 文件路径: ai_agent/scripts/setup_pgvector.sql
```

```bash
# 方式B：命令行
psql -h 115.191.40.53 -U postgres -d lejiyou_rag -f scripts/setup_pgvector.sql
```

执行后 `lejiyou_rag` 将新增：
- `scenic_vectors` / `hotel_vectors` / `route_vectors` / `vr_scenic_vectors` — 向量表
- `rag_index_status` — 索引构建状态追踪
- `v_chat_intent_stats` — 意图统计视图

---

### 步骤 2 — 启动 vLLM（LLM 推理服务）

#### GPU 服务器（生产）

```bash
# 安装 vLLM
pip install vllm

# 启动（首次会自动下载 Qwen2.5-7B-Instruct，约 15GB）
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --host 0.0.0.0 \
    --port 8001 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.85 \
    --api-key EMPTY \
    --trust-remote-code
```

#### Docker GPU 模式

```bash
cd ai_agent
docker-compose --profile gpu up -d vllm
docker-compose logs -f vllm   # 等待 "Uvicorn running" 日志
```

#### 无 GPU 开发调试（CPU 小模型）

```bash
docker-compose --profile cpu up -d vllm-cpu
# 使用 Qwen2.5-1.5B-Instruct，速度慢但可用
```

验证 vLLM：
```bash
curl http://localhost:8001/v1/models
# 应返回模型名称列表
```

---

### 步骤 3 — 安装 Python 依赖

```bash
cd ai_agent

# 创建虚拟环境
python -m venv .venv

# Windows 激活
.venv\Scripts\activate

# 安装依赖（建议先装 CPU 版 PyTorch 节省时间）
pip install torch==2.3.0 --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
```

---

### 步骤 4 — 配置环境变量

`.env` 已预填关键配置，确认以下几项正确：

```ini
# PostgreSQL（lejiyou_rag）
PG_HOST=115.191.40.53
PG_PORT=5432
PG_DATABASE=lejiyou_rag
PG_USER=postgres
PG_PASSWORD=postgres123          # ← 确认密码

# vLLM（本地启动则 localhost，Docker 内则为容器名）
VLLM_BASE_URL=http://localhost:8001/v1
VLLM_MODEL_NAME=Qwen/Qwen2.5-7B-Instruct

# Redis
REDIS_HOST=115.191.40.53
REDIS_PASSWORD=Redis@2026!Def1234567890
```

---

### 步骤 5 — 启动 FastAPI 智能体服务

```bash
# 开发模式（热重载）
python main.py

# 生产模式
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2
```

验证：
```bash
curl http://localhost:8000/health
```

预期响应：
```json
{
  "status": "ok",
  "components": {
    "agent": "ok",
    "postgres": "ok",
    "redis": "ok",
    "vllm": "ok"
  }
}
```

---

### 步骤 6 — 构建 RAG 向量索引

**首次必须执行**（先往 `scenic`/`hotel`/`tour_route` 等表导入数据再执行）：

```bash
# 方式A：HTTP 接口触发（服务启动后）
curl -X POST http://localhost:8000/api/agent/index/build \
  -H "Content-Type: application/json" \
  -d '{"source":"mysql","force_rebuild":true}'

# 方式B：直接运行 Python 脚本
python -c "
from rag.indexer import TourismIndexer
indexer = TourismIndexer()
count = indexer.build_all(force_rebuild=True)
print(f'索引构建完成：{count} 条文档')
"
```

> ⏱ 首次构建约 5~15 分钟（取决于数据量，嵌入模型首次加载需额外时间）

---

### 步骤 7 — 测试对话

```bash
curl -X POST http://localhost:8000/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "test-001",
    "message": "帮我推荐一下河北承德附近有哪些景区",
    "location": "承德",
    "stream": false
  }'
```

---

## Java 后端对接说明

Java 端已实现 `AgentController` + `AgentServiceImpl`，无需修改。
确认 `application.yml` 中配置正确：

```yaml
agent:
  service:
    url: http://localhost:8000    # Python FastAPI 地址
    timeout: 30000
```

Java 调用的接口路径（已实现）：

| Java 调用 | Python 接口 | 说明 |
|----------|------------|------|
| `agentService.chat(req)` | `POST /api/agent/chat` | 同步对话 |
| `agentService.chatStream(req)` | `POST /api/agent/chat`（stream=true）| SSE 流式 |
| `agentService.submitScore(...)` | `POST /api/agent/score` | 提交评分 |
| `agentService.triggerIndexBuild(...)` | `POST /api/agent/index/build` | 触发索引重建 |

---

## 小程序端调用示例

```javascript
// pages/ai-chat/ai-chat.js

// ── 普通对话 ──────────────────────────────────────────────────
sendMessage(text) {
  uni.request({
    url: `${BASE_URL}/agent/chat`,
    method: 'POST',
    header: { 'Authorization': 'Bearer ' + uni.getStorageSync('token') },
    data: {
      message: text,
      location: this.currentCity,
      stream: false
    },
    success: ({ data }) => {
      const { answer, intent, suggestions } = data.data;
      this.appendMessage('assistant', answer);
      this.suggestions = suggestions;
    }
  });
},

// ── 流式对话（打字机效果）────────────────────────────────────────
// 注意：微信小程序不支持原生 EventSource
// 使用 uni-app 插件 or 轮询 or WebSocket 替代
sendMessageStream(text) {
  const task = uni.request({
    url: `${BASE_URL}/agent/chat/stream?sessionId=${this.sessionId}&message=${encodeURIComponent(text)}`,
    method: 'GET',
    header: { 'Authorization': 'Bearer ' + uni.getStorageSync('token') },
    enableChunked: true,  // 分块传输
    success: () => {},
  });
  task.onChunkReceived(({ data }) => {
    const lines = new TextDecoder().decode(data).split('\n');
    lines.forEach(line => {
      if (line.startsWith('data:')) {
        const chunk = JSON.parse(line.slice(5));
        if (chunk.type === 'token') this.appendToken(chunk.content);
        if (chunk.type === 'done') this.onStreamDone(chunk);
      }
    });
  });
}
```

---

## 意图路由说明

| 用户输入关键词 | 分类意图 | 触发动作 |
|--------------|---------|---------|
| 景区、景点、门票、打卡 | `scenic_query` | RAG检索 + scenic工具查询 |
| 酒店、住宿、民宿、宾馆 | `hotel_query` | RAG检索 + hotel工具查询 |
| 路线、行程、几日游、攻略 | `route_planning` | RAG检索 + route工具查询 |
| 天气、气温、下雨 | `weather_query` | 天气API工具 |
| VR、虚拟、全景 | `vr_scenic` | RAG检索 + vr_scenic工具 |
| 其他 | `general_chat` | 直接生成回答 |

---

## 常见问题

**Q: pgvector 扩展无法创建？**
```sql
-- 确认服务器已安装 pgvector 包
SELECT * FROM pg_available_extensions WHERE name = 'vector';
-- 若无结果，联系服务器管理员安装: apt install postgresql-16-pgvector
```

**Q: 嵌入模型下载慢？**
```bash
# 设置 HuggingFace 镜像
export HF_ENDPOINT=https://hf-mirror.com
python main.py
```

**Q: vLLM 内存不足？**
```bash
# 降低 GPU 内存占用或换小模型
--gpu-memory-utilization 0.7
--model Qwen/Qwen2.5-3B-Instruct
```

**Q: RAG 检索结果为空？**
先确认数据已导入 `lejiyou_rag` 的业务表，再重新触发索引构建：
```bash
curl -X POST http://localhost:8000/api/agent/index/build \
  -d '{"force_rebuild":true}'
```