# 知识库管理说明

## 当前方案

默认运行模式：`KNOWLEDGE_SEARCH_MODE=lite`

- Bot 运行镜像不安装 `torch` / `sentence-transformers` / `numpy`
- 运行时只读取 `knowledge/index/metadata.json`
- 使用轻量关键词 + 领域词表 + BM25-like 加权检索
- 命中后仍调用 Ollama 生成最终中文回答

## 为什么这样设计

原方案运行时需要给用户问题生成 embedding，因此 Docker 镜像必须包含 `sentence-transformers -> torch/CUDA`，镜像约 6GB。

当前轻量方案把运行镜像降到约 175MB，常见问答命中仍然准确，性价比最高。

## 常用命令

### 重建轻量 metadata/向量索引（宿主机）

```bash
cd /vol3/1000/Code/tg-spam-guard
.venv/bin/python3 build_kb.py
```

> `build_kb.py` 仍会生成 `embeddings.npy`，方便以后切回 vector 模式；运行镜像只使用 `metadata.json`。

### 运行时轻量检索测试

```bash
cd /vol3/1000/Code/tg-spam-guard
KNOWLEDGE_SEARCH_MODE=lite .venv/bin/python3 -c "from knowledge import search; print(search('怎么安装收割机', top_k=3))"
```

### 可选：向量检索模式

仅建议宿主机/开发环境使用：

```bash
KNOWLEDGE_SEARCH_MODE=vector .venv/bin/python3 -c "from knowledge import search; print(search('怎么安装收割机', top_k=3))"
```

需要安装离线依赖：

```bash
pip install -r requirements-kb.txt
```

## Docker 注意事项

`docker-compose.yaml` 显式设置：

```yaml
KNOWLEDGE_SEARCH_MODE: lite
```

并挂载：

```yaml
./knowledge/index:/app/knowledge/index
./knowledge/qa_cache.json:/app/knowledge/qa_cache.json
```

只要 `knowledge/index/metadata.json` 存在，轻量检索即可工作。