# agent

**Repository Path**: lzppub/agent

## Basic Information

- **Project Name**: agent
- **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-08-29
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent —— 多智能体学习平台

> 个人学习 AI Agent 技术的实验平台，通过多个子项目实践不同的智能体能力。

## 项目简介

本项目是一个 **多智能体学习平台**，采用模块化的项目架构，将不同的 AI Agent 实践项目组织在统一的代码仓库中。每个子项目专注于一个方向，共享基础设施（模型服务、数据库、配置管理）。

**当前包含的子项目：**

| 子项目 | 目录 | 说明 | 状态 |
|--------|------|------|------|
| 企业知识库（RAG） | `knowledge_base/` | 文档解析 + 向量检索 + LLM 流式问答 | 已实现 |
| 提示词工程演示 | `prompt_lab/` | 提示词模板管理 + 实验对比 + 学习笔记 | 骨架已创建 |

---

## 项目结构

```
agent/                              # 项目根目录
│
├── config/                         # ★ 集中式环境配置管理
│   └── __init__.py                 #   配置加载器（读取 .env.{profile}）
│
├── shared/                         # ★ 多项目共享的公共模块
│   ├── llm/                        #   LLM 客户端封装（OpenAI 兼容 API）
│   ├── db/                         #   数据库连接工具（PG / Milvus / Neo4j）
│   └── utils/                      #   通用工具（连接检测等）
│
├── knowledge_base/                 # ★ 子项目一：企业知识库（RAG）
│   ├── kb-server/                  #   FastAPI 后端（SSE 流式问答）
│   │   ├── app/
│   │   │   ├── config.py           #     配置加载（从根 config 读取 + KB_ 覆盖）
│   │   │   ├── main.py             #     FastAPI 入口
│   │   │   ├── routers/            #     API 路由（chat / documents / logs）
│   │   │   ├── services/           #     业务逻辑（LLM / RAG / 向量库 / 解析器）
│   │   │   └── tasks/              #     异步任务（文档导入）
│   │   ├── scripts/                #     运维脚本（rerank 服务 / dev 启动）
│   │   ├── docker-compose.dev.yml  #     本机依赖服务（PG / Milvus / Neo4j）
│   │   ├── run.sh                  #     启动脚本（支持 --profile dev|prod）
│   │   └── requirements.txt        #     Python 依赖
│   ├── kb-web/                     #   Vue3 + Element Plus 前端
│   │   └── src/views/              #     页面（Chat / KnowledgeBase / Status）
│   ├── deploy/                     #   部署配置（systemd + nginx）
│   └── knowledge_doc/              #   示例文档
│
├── prompt_lab/                     # ★ 子项目二：提示词工程演示
│   ├── kb-server/                  #   FastAPI 后端（实验管理 + 模板管理）
│   │   ├── app/
│   │   │   ├── config.py           #     配置（从根 config 读取）
│   │   │   ├── main.py             #     FastAPI 入口
│   │   │   ├── routers/            #     API 路由（experiments / templates）
│   │   │   └── services/           #     业务逻辑（实验运行 / 模板加载）
│   │   ├── run.sh                  #     启动脚本
│   │   └── requirements.txt        #     Python 依赖
│   ├── kb-web/                     #   Vue3 前端
│   │   └── src/views/              #     页面（Experiment / Templates / Compare）
│   ├── docs/                       #   学习笔记（提示词工程知识点）
│   └── examples/                   #   提示词示例（Zero-Shot / Few-Shot / CoT）
│
├── kb/                             # Agent 通用 schema / DAO（知识库数据模型）
├── tests/                          # 各模块的 pytest 测试
├── docs/                           # 全局设计文档
│
├── .env.dev                        # 开发环境配置（不提交 Git）
├── .env.prod                       # 生产环境配置（不提交 Git）
├── .env.dev.example                # 开发环境配置模板
├── .env.prod.example               # 生产环境配置模板
├── requirements.txt                # 全局 Python 依赖
├── requirements-dev.txt            # 开发/测试依赖
└── pytest.ini                      # pytest 配置
```

---

## 环境配置管理

### 设计思路

项目采用 **集中式环境配置管理**，所有子项目共享同一套环境配置：

```
config/__init__.py          ← 配置加载器（读取 .env.{profile}）
    ↑
    ├── knowledge_base/kb-server/app/config.py  ← 导入根配置 + KB_ 前缀覆盖
    ├── prompt_lab/kb-server/app/config.py      ← 导入根配置 + PL_ 前缀覆盖
    └── shared/db/__init__.py                   ← 直接使用根配置
```

### Profile 切换

通过环境变量选择环境配置：

| 环境变量 | 说明 | 示例 |
|----------|------|------|
| `AGENT_PROFILE` | 全局 profile（推荐） | `AGENT_PROFILE=prod` |
| `KB_PROFILE` | 仅知识库子项目（向后兼容） | `KB_PROFILE=prod` |

可选值：
- `dev`（默认）→ 本机开发环境，连接 localhost 上的 Docker / Ollama
- `prod` → 远程服务器环境，连接 192.168.1.16 上的服务

### .env 文件

| 文件 | 用途 | 是否提交 Git |
|------|------|-------------|
| `.env.dev.example` | 开发环境配置模板 | 是 |
| `.env.prod.example` | 生产环境配置模板 | 是 |
| `.env.dev` | 开发环境实际配置 | 否（含密码） |
| `.env.prod` | 生产环境实际配置 | 否（含密码） |

### 配置变量优先级（从高到低）

1. shell 中 `export` 的环境变量
2. 子项目 `.env.{profile}`（如 `KB_PG_HOST`）
3. 根目录 `.env.{profile}`（如 `PG_HOST`）
4. `config/__init__.py` 中的默认值

### 外部服务清单

| 服务 | 用途 | dev 地址 | prod 地址 |
|------|------|----------|-----------|
| PostgreSQL | 对话日志 / 审计数据 | localhost:5432 | 192.168.1.16:5433 |
| Milvus | 向量数据库（语义检索） | localhost:19530 | 192.168.1.16:19531 |
| Neo4j | 图数据库（预留） | localhost:7687 | 192.168.1.16:7687 |
| Chat 模型 | 主对话模型 | Ollama qwen3:4b | vLLM qwen3.8-27b |
| Embedding | 文本向量化 | Ollama nomic-embed-text | vLLM qwen3-embedding-4b |
| Rerank | 文档重排序 | 本地 bge-reranker | vLLM qwen3-reranker-4b |

---

## 快速启动

### 前置条件

- Docker（用于运行 PostgreSQL / Milvus / Neo4j）
- Python 3.11+
- Node.js 18+（前端开发）
- Ollama（dev 环境的模型推理）

### 企业知识库

```bash
# 1. 后端（自动启动 Docker 依赖 + Ollama 检查）
cd knowledge_base/kb-server
./scripts/start_dev.sh

# 2. 前端（另一个终端）
cd knowledge_base/kb-web
npm install && npm run dev

# 3. 浏览器打开 http://localhost:5173
```

### 提示词工程演示

```bash
# 1. 后端
cd prompt_lab/kb-server
pip install -r requirements.txt
./run.sh  # 默认 dev profile，端口 8001

# 2. 前端（另一个终端）
cd prompt_lab/kb-web
npm install && npm run dev

# 3. 浏览器打开 http://localhost:5174
```

### 切换到生产环境（116 服务器）

```bash
# 方式一：全局 profile
AGENT_PROFILE=prod ./run.sh

# 方式二：仅知识库
KB_PROFILE=prod ./run.sh
```

### 连接检测

```bash
# 一键检测所有外部服务是否可用
python -m shared.utils.connection_test
```

---

## 共享模块说明（shared/）

`shared/` 目录存放多个子项目共用的工具代码，避免重复实现。

### shared/llm/ — LLM 客户端

封装 OpenAI 兼容 API 的通用客户端，支持：
- 同步/流式对话（chat completions）
- 文本向量化（embeddings）
- 健康检查（health check）

```python
from shared.llm import LLMClient

client = LLMClient(
    base_url="http://127.0.0.1:11434",
    api_key="ollama",
    model="qwen3:4b"
)
answer = await client.chat("你好")
```

### shared/db/ — 数据库连接

提供 PostgreSQL / Milvus / Neo4j 的连接池管理：

```python
from shared.db import get_pg_connection, get_milvus_client

conn = get_pg_connection()   # PostgreSQL 连接（从连接池获取）
client = get_milvus_client() # Milvus 客户端单例
```

### shared/utils/ — 通用工具

- `connection_test.py`：一键检测所有外部服务连接状态

---

## 新增子项目指南

如果你想添加新的智能体项目（如 Agent 工作流、RAG 进阶等），按以下步骤操作：

### 1. 创建项目目录

```
agent/
└── your_project/              # 你的新项目
    ├── kb-server/             #   后端（参考 prompt_lab/kb-server）
    │   ├── app/
    │   │   ├── __init__.py
    │   │   ├── config.py      #   从根 config 导入共享配置
    │   │   ├── main.py        #   FastAPI 入口
    │   │   ├── routers/       #   API 路由
    │   │   └── services/      #   业务逻辑
    │   ├── requirements.txt
    │   └── run.sh
    ├── kb-web/                #   前端
    ├── docs/                  #   学习笔记
    └── README.md
```

### 2. 创建 config.py

```python
# your_project/kb-server/app/config.py
import sys
from pathlib import Path

# 将根目录加入 sys.path
_PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent.parent
sys.path.insert(0, str(_PROJECT_ROOT))

# 从根 config 导入共享配置
from config import PROFILE, MODELS, PG

# 你的项目特有配置...
```

### 3. 使用共享模块

```python
from shared.llm import LLMClient
from shared.db import get_pg_connection
```

---

## 学习资源

### 项目内学习材料

- `prompt_lab/docs/提示词工程知识点.md` — 提示词工程核心知识
- `prompt_lab/examples/` — Zero-Shot / Few-Shot / CoT 示例
- `shared/llm/__init__.py` — LLM API 调用详解（中文注释）
- `shared/db/__init__.py` — 数据库知识科普（中文注释）
- `shared/utils/connection_test.py` — 服务连接检测原理

### 外部资源

- [LangChain 文档](https://python.langchain.com/docs/)
- [Prompt Engineering Guide](https://www.promptingguide.ai/zh)
- [RAG 论文](https://arxiv.org/abs/2005.11401)

---

## 技术栈

### 后端
- **FastAPI** — 高性能 Python Web 框架
- **httpx** — 异步 HTTP 客户端（调用 LLM API）
- **psycopg2** — PostgreSQL 驱动
- **pymilvus** — Milvus 向量数据库 SDK
- **neo4j** — Neo4j 图数据库驱动

### 前端
- **Vue 3** — 渐进式 JavaScript 框架
- **Element Plus** — Vue 3 组件库
- **Vite** — 下一代前端构建工具
- **Axios** — HTTP 客户端

### 基础设施
- **Ollama** — 本地模型推理（dev 环境）
- **vLLM** — 高性能模型推理（prod 环境）
- **Docker Compose** — 本机依赖服务编排