# internal-agent

**Repository Path**: dingshuanglei/internal-agent

## Basic Information

- **Project Name**: internal-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-26
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 内部智能手册知识库 Agent

基于 RAG（检索增强生成）架构的企业内部知识库智能问答系统，支持多格式文档解析、向量化检索、智能问答、权限管理和数据统计。

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | Vue 3 + Element Plus + Vite |
| 后端 | Python FastAPI + SQLAlchemy |
| 数据库 | PostgreSQL 16 + pgvector |
| 大模型 | Ollama（OpenAI 兼容 API） |
| 文档解析 | PyPDF2, python-docx, openpyxl |
| 认证 | JWT Token |
| 部署 | Docker Compose 一键部署 |

## 项目结构

```
internal-agent/
├── backend/                    # Python FastAPI 后端
│   ├── app/
│   │   ├── api/                # API 路由层
│   │   │   ├── auth.py         # 登录/注册认证
│   │   │   ├── documents.py    # 文档上传/审核/管理
│   │   │   ├── qa.py           # 智能问答（单次+流式 SSE）
│   │   │   ├── knowledge.py    # 知识库分类管理
│   │   │   ├── stats.py        # 数据统计/审计日志
│   │   │   └── admin.py        # 用户管理
│   │   ├── core/               # 基础设施
│   │   │   ├── database.py     # 数据库引擎
│   │   │   ├── security.py     # JWT/权限/敏感词
│   │   │   └── middleware.py   # 请求日志/CORS
│   │   ├── models/             # ORM 数据模型
│   │   ├── services/           # 核心业务服务
│   │   │   ├── vector_service.py   # 向量库操作
│   │   │   ├── llm_service.py      # 大模型 + Prompt
│   │   │   ├── search_service.py   # 混合检索
│   │   │   ├── document_service.py # 文档管理
│   │   │   └── auth_service.py     # 认证服务
│   │   └── utils/              # 工具模块
│   │       ├── file_parser.py      # PDF/Word/TXT/Excel 解析
│   │       ├── text_splitter.py    # 智能文本切片
│   │       └── embedding.py        # BGE 中文向量化
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/                   # Vue3 + Element Plus 前端
│   ├── src/
│   │   ├── views/
│   │   │   ├── Login.vue       # 登录页
│   │   │   ├── QAChat.vue      # 智能问答聊天（流式）
│   │   │   ├── KnowledgeBase.vue   # 知识库浏览
│   │   │   ├── AdminDocument.vue   # 文档管理
│   │   │   ├── AdminUsers.vue      # 用户管理
│   │   │   └── Statistics.vue      # 统计面板
│   │   ├── components/         # 通用组件
│   │   ├── api/                # API 封装
│   │   ├── router/             # 路由 + 权限守卫
│   │   └── store/              # Pinia 状态管理
│   ├── Dockerfile
│   └── nginx.conf
├── postgres/init.sql            # 数据库初始化脚本
├── docker-compose.yml          # 前后端服务编排
├── start.sh                    # Linux/Mac 启动脚本
├── dev.bat                     # Windows 开发环境脚本
└── README.md
```

## 数据库架构

使用 **PostgreSQL 16 + pgvector** 扩展，业务数据与向量存储一体化，单数据库管理。基础设施服务（PostgreSQL + Ollama）已部署在 `192.168.100.130`。

## 核心功能

### 1. 私有知识库管理
- 支持 PDF、Word、TXT、Markdown、Excel 多格式文档上传
- 智能章节切片 + 滑动窗口重叠策略
- 文档分类树管理、审核流程
- 向量化入库与增量更新

### 2. 智能问答 Agent
- 基于 RAG 的自然语言问答
- 流式 SSE 实时输出，支持 Markdown 渲染
- 多轮对话记忆（最近 10 轮）
- 答案溯源标注，引用来源文档和段落
- 模糊问题引导补全
- 用户反馈评价（有帮助/无帮助）

### 3. 混合检索
- pgvector 向量语义检索 + PostgreSQL 关键词精确匹配
- 混合排序算法，相似度阈值过滤
- 支持按知识库分类筛选

### 4. Prompt 工程
- 私域约束：仅基于内部知识库作答
- 无数据不编造：明确告知无相关信息
- 溯源优先：回答附带引用来源
- 流程编号：操作指南按步骤输出
- 敏感内容屏蔽

### 5. 权限安全
- JWT Token 认证
- 四级角色：admin / manager / editor / viewer
- 接口级权限控制
- 敏感词检测过滤
- 全操作审计日志

### 6. 数据统计
- 问答总量、回答率、平均响应时间
- 高频问题 TOP20
- 未回答问题台账
- 用户活跃度统计

## 快速开始

### 环境要求

- Docker & Docker Compose（2.0+）
- 或 Python 3.10+ / Node.js 18+

### 前置条件

确保以下服务已就绪：

| 服务 | 地址 | 说明 |
|------|------|------|
| PostgreSQL 16 + pgvector | `192.168.100.130:5433` | 用户名/密码：`postgres` |
| Ollama | `192.168.100.130:11434` | OpenAI 兼容 API |

### Docker 部署

```bash
# 克隆项目
git clone <repo-url> && cd internal-agent

# 一键启动前后端
docker compose up -d --build

# 查看日志
docker compose logs -f

# 访问
# 前端: http://localhost
# API 文档: http://localhost:8000/docs
# 默认管理员: admin / 123456
```

### 开发模式

```bash
# 1. 后端
cd backend

# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 使用国内镜像加速安装（推荐）
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
python -m uvicorn app.main:app --reload --port 8000

# 2. 新终端，前端
cd frontend
npm install --registry https://registry.npmmirror.com
npm run dev
# 访问 http://localhost:5266
```

### 初始化

首次使用需要初始化管理员账号：

```bash
# 方式一：使用初始化脚本
cd backend
python init_admin.py

# 方式二：调用 API
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456","role":"admin"}'
```

> pgvector 扩展会在应用启动时自动启用，无需手动初始化。

## API 接口概览

| 模块 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 认证 | POST | `/api/v1/auth/login` | 用户登录 |
| 认证 | POST | `/api/v1/auth/register` | 用户注册 |
| 文档 | POST | `/api/v1/documents/upload` | 上传文档 |
| 文档 | GET | `/api/v1/documents` | 文档列表 |
| 文档 | PUT | `/api/v1/documents/{id}/review` | 审核文档 |
| 问答 | POST | `/api/v1/qa/ask` | 智能问答 |
| 问答 | GET | `/api/v1/qa/chat/stream` | 流式问答(SSE) |
| 知识库 | GET | `/api/v1/knowledge/categories` | 分类列表 |
| 知识库 | POST | `/api/v1/knowledge/categories` | 创建分类 |
| 统计 | GET | `/api/v1/stats/overview` | 统计概览 |
| 统计 | GET | `/api/v1/stats/unanswered` | 未回答问题 |
| 管理 | GET | `/api/v1/admin/users` | 用户列表 |
| 管理 | PUT | `/api/v1/admin/users/{id}` | 编辑用户 |

完整 API 文档请访问：`http://localhost:8000/docs` (Swagger UI)

## 环境变量

后端配置位于 `backend/.env`：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DB_HOST` | PostgreSQL 地址 | `192.168.100.130` |
| `DB_PORT` | PostgreSQL 端口 | `5433` |
| `DB_USER` | 用户名 | `postgres` |
| `DB_PASSWORD` | 密码 | `postgres` |
| `DB_NAME` | 数据库名 | `knowledge_agent_db` |
| `LLM_ENDPOINT` | Ollama API 地址 | `http://192.168.100.130:11434/v1` |
| `LLM_MODEL` | 对话模型 | `qwen2.5:1.5b` |
| `EMBEDDING_MODEL` | 向量模型 | `BAAI/bge-base-zh-v1.5` |
| `VECTOR_DIM` | 向量维度 | `768` |
| `JWT_SECRET_KEY` | JWT 密钥 | (请修改为随机字符串) |
| `UPLOAD_DIR` | 文件上传目录 | `./uploads` |

## 角色权限

| 权限 | admin | manager | editor | viewer |
|------|-------|---------|--------|--------|
| 问答提问 | ✅ | ✅ | ✅ | ✅ |
| 浏览知识库 | ✅ | ✅ | ✅ | ✅ |
| 上传文档 | ✅ | ✅ | ✅ | ❌ |
| 审核文档 | ✅ | ✅ | ❌ | ❌ |
| 管理用户 | ✅ | ❌ | ❌ | ❌ |
| 查看统计 | ✅ | ✅ | ❌ | ❌ |
| 查看日志 | ✅ | ✅ | ❌ | ❌ |