# agent-knowledge-base-system

**Repository Path**: cczeros/agent-knowledge-base-system

## Basic Information

- **Project Name**: agent-knowledge-base-system
- **Description**: agent-knowledge-base-system
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent 专属知识库系统

为企业级 AI Agent 构建的专属知识库系统，支持文档管理、语义检索、RAG 问答和多 Agent 知识隔离。

## 核心特性

- **知识沉淀**：支持 PDF、Word、Markdown、TXT、HTML、CSV 等多种文档格式
- **智能切片**：固定大小切片 + 语义切片 + 自定义规则，支持多粒度索引
- **精准检索**：向量检索 + 关键词检索多路召回 + 重排序
- **RAG 问答**：检索增强生成，支持流式输出和多轮对话
- **Agent 隔离**：多 Agent 知识空间隔离，API Key 认证
- **异步处理**：文档上传后异步解析、切片、向量化

## 快速开始

### 环境要求

- Python 3.11+
- PostgreSQL 16 + pgvector
- Redis 7
- Docker & Docker Compose (可选)

### 1. 克隆项目

```bash
cd agent-knowledge-base-system
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入 OpenAI API Key 等配置
```

### 3. Docker Compose 一键部署（推荐）

```bash
docker-compose -f docker/docker-compose.yml up -d
```

### 4. 本地开发部署

```bash
# 安装依赖
pip install -r requirements.txt

# 启动 PostgreSQL (需要 pgvector 扩展)
docker run -d --name agent-kb-pg \
  -e POSTGRES_DB=agent_kb \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  pgvector/pgvector:pg16

# 启动 Redis
docker run -d --name agent-kb-redis -p 6379:6379 redis:7-alpine

# 初始化数据库
psql -h localhost -U postgres -d agent_kb -f migrations/init.sql

# 启动 API 服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 启动 Celery Worker (新终端)
celery -A app.celery_app worker -Q document_processing --concurrency=4 -l info
```

### 5. 访问 API 文档

- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 使用指南

### 1. 注册 Agent 获取 API Key

```bash
curl -X POST http://localhost:8000/api/v1/agents \
  -H "Content-Type: application/json" \
  -d '{"name": "客服Agent", "description": "处理用户售后咨询"}'
```

返回的 `api_key` 只显示一次，请妥善保存。

### 2. 创建知识库

```bash
curl -X POST http://localhost:8000/api/v1/knowledge-bases \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak-your-api-key" \
  -d '{"name": "售后知识库", "description": "退款、换货、保修政策"}'
```

### 3. 上传文档

```bash
curl -X POST http://localhost:8000/api/v1/knowledge-bases/{kb_id}/documents \
  -H "X-API-Key: ak-your-api-key" \
  -F "file=@refund-policy.pdf"
```

文档上传后会在后台异步处理（解析 → 切片 → 向量化）。

### 4. 检索知识

```bash
curl -X POST http://localhost:8000/api/v1/knowledge-bases/{kb_id}/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak-your-api-key" \
  -d '{"query": "如何申请退款？", "top_k": 5}'
```

### 5. RAG 问答

```bash
curl -X POST http://localhost:8000/api/v1/knowledge-bases/{kb_id}/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak-your-api-key" \
  -d '{"query": "退款需要多长时间到账？"}'
```

### Python SDK 使用

```python
from sdk.client import KnowledgeBaseClient

# 初始化客户端
client = KnowledgeBaseClient(
    base_url="http://localhost:8000",
    api_key="ak-your-api-key",
)

# 检索知识
results = client.search("如何退款？", kb_id="your-kb-id")

# RAG 问答
answer = client.chat("退款流程是什么？", kb_id="your-kb-id")
print(answer["answer"])

# 流式问答
for token in client.chat_stream("退货需要什么条件？", kb_id="your-kb-id"):
    print(token, end="")

# 上传文档
client.upload_document(
    kb_id="your-kb-id",
    file_path="./docs/policy.pdf",
    metadata={"category": "售后", "version": "v2.0"},
)
```

## 项目结构

```
agent-knowledge-base-system/
├── app/
│   ├── main.py                 # FastAPI 应用入口
│   ├── config.py               # 配置管理
│   ├── database.py             # 数据库连接
│   ├── celery_app.py           # Celery 配置
│   ├── api/                    # API 路由
│   │   ├── agent.py            # Agent 管理 API
│   │   ├── knowledge.py        # 知识管理 API
│   │   ├── retrieval.py        # 检索与问答 API
│   │   └── admin.py            # 管理后台 API
│   ├── models/                 # 数据模型 (SQLAlchemy)
│   │   ├── __init__.py         # Agent 模型
│   │   ├── knowledge_base.py   # 知识库模型
│   │   ├── document.py         # 文档模型
│   │   ├── chunk.py            # 切片模型
│   │   └── conversation.py     # 对话模型
│   ├── schemas/                # Pydantic Schema
│   ├── services/               # 业务逻辑层
│   │   ├── document_service.py # 文档处理服务
│   │   ├── embedding_service.py# Embedding 服务
│   │   ├── retrieval_service.py# 检索服务
│   │   ├── llm_service.py      # LLM 调用服务
│   │   └── agent_service.py    # Agent 管理服务
│   ├── core/                   # 核心组件
│   │   ├── parser.py           # 文档解析器
│   │   ├── chunker.py          # 文本切片器
│   │   ├── vector_store.py     # Milvus 向量存储
│   │   └── security.py         # 安全认证
│   └── tasks/                  # Celery 异步任务
│       └── document_tasks.py   # 文档处理任务
├── sdk/
│   └── client.py               # Python SDK 客户端
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── migrations/
│   └── init.sql                # 数据库初始化脚本
├── tests/                      # 测试用例
├── docs/
│   └── DESIGN.md               # 完整设计方案
├── requirements.txt
├── .env.example
└── README.md
```

## API 概览

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/agents` | 注册 Agent |
| GET | `/api/v1/agents` | Agent 列表 |
| GET | `/api/v1/agents/{id}` | Agent 详情 |
| PUT | `/api/v1/agents/{id}` | 更新 Agent |
| DELETE | `/api/v1/agents/{id}` | 注销 Agent |
| POST | `/api/v1/agents/{id}/regenerate-key` | 重新生成 API Key |
| POST | `/api/v1/knowledge-bases` | 创建知识库 |
| GET | `/api/v1/knowledge-bases` | 知识库列表 |
| GET | `/api/v1/knowledge-bases/{id}` | 知识库详情 |
| PUT | `/api/v1/knowledge-bases/{id}` | 更新知识库 |
| DELETE | `/api/v1/knowledge-bases/{id}` | 删除知识库 |
| POST | `/api/v1/knowledge-bases/{id}/documents` | 上传文档 |
| GET | `/api/v1/knowledge-bases/{id}/documents` | 文档列表 |
| DELETE | `/api/v1/knowledge-bases/documents/{id}` | 删除文档 |
| POST | `/api/v1/knowledge-bases/{id}/search` | 知识检索 |
| POST | `/api/v1/knowledge-bases/{id}/chat` | RAG 问答 |
| POST | `/api/v1/knowledge-bases/{id}/chat/stream` | 流式问答 |
| GET | `/api/v1/knowledge-bases/{id}/conversations` | 对话历史 |
| GET | `/api/v1/admin/health` | 健康检查 |
| GET | `/api/v1/admin/stats` | 系统统计 |

## 技术栈

- **Web 框架**：FastAPI (异步高性能)
- **数据库**：PostgreSQL 16 + pgvector (向量存储)
- **向量数据库**：Milvus (可选，大规模场景)
- **缓存/队列**：Redis + Celery
- **Embedding**：OpenAI text-embedding-3-large / 兼容中文 bge-large-zh
- **LLM**：OpenAI GPT-4o / 兼容 API
- **对象存储**：MinIO (可选)

## License

MIT