# 拓竹知识库 api

**Repository Path**: threezhuge/tuozhu-knowledge-base-api

## Basic Information

- **Project Name**: 拓竹知识库 api
- **Description**: 知识库api获取微服务
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: feature-knowledge-pipeline-phase1
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KB Ingestion Service

知识库文档入库服务 — 将文档安全、可靠地写入 HiAgent 知识库的中间层 pipeline。

## 功能概览

- **文件上传** — 支持 13 种常见格式（txt, md, doc, docx, ppt, pptx, pdf, xlsx, xls, csv, tsv, json, jsonl），单文件最大 100 MB
- **持久化任务队列** — 基于 SQLite，重启不丢失，失败自动重试
- **前缀路由** — 按 `source_key` 前缀自动路由到目标知识库
- **版本管理** — 基于 `source_document_id` 的文档版本历史追踪
- **智能去重** — 三重指纹（`raw_hash` / `content_hash` / `config_hash`）驱动，避免重复入库
- **Safe Rebuild** — 需要更新时先建新文档，成功后再切换，保证数据一致
- **幂等提交** — 同一请求重复调用不会产生副作用
- **Webhook 回调** — 任务完成或失败时主动通知调用方
- **管理界面** — 内置 Vue 3 前端，可视化管理文档与任务；路由配置支持只读查看（创建/编辑请使用 API）

## 技术栈

| 层 | 技术 |
| --- | --- |
| 后端框架 | Python 3.11 + FastAPI |
| 异步运行时 | Uvicorn |
| 数据库 | SQLite（aiosqlite） |
| HTTP 客户端 | httpx |
| 前端 | Vue 3 + TypeScript + Element Plus |
| 构建与部署 | Docker 多阶段构建，单容器单端口 |

## 项目结构

```text
├── app/                    # 后端源码
│   ├── main.py             # FastAPI 应用入口
│   ├── config.py           # 配置与路由表
│   ├── database.py         # SQLite 数据层
│   ├── hiagent_client.py   # HiAgent 平台客户端
│   ├── ingestion.py        # 入库核心逻辑
│   ├── job_worker.py       # 后台任务处理器
│   ├── models.py           # Pydantic 数据模型
│   └── routers/            # API 路由
├── frontend/               # Vue 3 前端
├── config/
│   └── routes.yaml         # 路由配置
├── tests/                  # 测试用例
├── scripts/                # 辅助脚本
├── Dockerfile              # 多阶段构建
├── docker-compose.yml      # 编排配置
├── LICENSE                 # Apache 2.0 许可证
├── requirements.txt        # Python 依赖
└── .env.example            # 环境变量模板
```

## 快速开始

### 前置条件

- Docker >= 20.10
- Docker Compose >= 2.0
- 可访问 HiAgent 平台

### 1. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入 HiAgent 平台凭证和服务密钥
```

关键配置项：

| 变量 | 说明 |
| --- | --- |
| `HIAGENT_HOST` | HiAgent 服务地址（含端口，不含协议） |
| `HIAGENT_AK` / `HIAGENT_SK` | HiAgent 访问凭证 |
| `HIAGENT_WORKSPACE_ID` | 目标工作空间 ID |
| `DOCUMENT_READY_GRACE_SECONDS` | 文档状态到 `9` 后，删除旧文档前额外等待的秒数，默认 `0` |
| `SERVICE_API_KEY` | 自定义 API 访问密钥 |

### 2. 配置路由（可选）

编辑 `config/routes.yaml`，定义 `source_key` 前缀到知识库的映射：

```yaml
routes:
  "zh/ProductA/":  "dataset-id-1"
  "en/ProductA/":  "dataset-id-2"
  "_default":      "dataset-id-fallback"
```

也可在服务启动后通过 `POST /routes` 接口动态创建。

### 3. 构建并启动

```bash
docker compose up -d --build
```

### 4. 验证

```bash
# 存活探针
curl http://localhost:18743/health

# 就绪探针
curl http://localhost:18743/ready
```

浏览器访问管理界面：<http://localhost:18743/>

### 5. 提交第一个文件

```bash
curl -X POST http://localhost:18743/documents/jobs \
  -H "Authorization: Bearer <your-service-api-key>" \
  -F "file=@test.md" \
  -F "client_namespace=my-app" \
  -F "source_document_id=doc-001"
```

查询任务状态：

```bash
curl http://localhost:18743/jobs/<job_id> \
  -H "Authorization: Bearer <your-service-api-key>"
```

`status` 变为 `completed` 即入库成功。

## 本地开发

### 后端

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 启动开发服务器
uvicorn app.main:get_app --reload --factory --port 18427
```

### 前端

```bash
cd frontend
npm install
npm run dev
```

### 测试

```bash
pytest tests/
```

## 数据持久化

| 容器路径 | 宿主机路径 | 说明 |
| --- | --- | --- |
| `/app/data/state.db` | `./data/state.db` | SQLite 数据库 |
| `/app/data/uploads/` | `./data/uploads/` | 上传文件存储 |
| `/app/config/` | `./config/` | 路由配置 |

> `./data` 目录包含所有服务状态，请做好备份。

## 端口说明

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| 容器监听端口 | `18427` | FastAPI 内部监听 |
| 宿主机映射端口 | `18743` | 对外访问端口 |

修改对外端口：编辑 `docker-compose.yml` 的 `ports` 映射。

## 文档

| 文档 | 说明 |
| --- | --- |
| [用户手册](用户手册.md) | 接入方式、使用示例、最佳实践 |
| [API 参考](API%20参考.md) | 接口规格、参数、错误码 |
| [部署指南](部署指南.md) | 环境配置、运维、常见问题排查 |

## License

本项目采用 Apache License 2.0。详见 [LICENSE](LICENSE)。