# Ai-RAG

**Repository Path**: ai-learning_3/ai-rag

## Basic Information

- **Project Name**: Ai-RAG
- **Description**: RAG（让AI有知识）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Local RAG System (FastAPI + Chroma + Whoosh + Ollama)

本项目是一个本地优先的工程化 RAG 系统，核心链路：

`Data Processing -> Hybrid Retrieval (Vector + Keyword + Metadata) -> LLM Generation`

## 核心能力

- 混合检索：向量召回 + 关键词召回 + 标签过滤
- 排序与分页：`score/freshness/popularity`、`offset`
- 搜索建议：`/search/suggest`
- 点击与曝光回流：`/search/click` + `track_exposure`
- 分析看板：`/search/analytics`、`/search/analytics/trend`
- 问答模式：
  - `strict_local_kb=true`：未命中拒答
  - `sources_mode=brief|full`：来源精简/完整

## 目录结构

```text
app/
  main.py
  config.py
  api/
    search.py
    chat.py
  core/
    embedding.py
    query_parser.py
    retriever.py
    reranker.py
    prompt.py
    llm.py
    analytics.py
    popularity.py
  data/
    loader.py
    splitter.py
    tagger.py
  index/
    vector_store.py
    keyword_store.py
  models/
    schema.py
scripts/
  build_index.py
  cleanup_analytics_logs.py
  watch_docs.py
  self_check.py
data/
  raw/
  processed/
```

## 1) 安装

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```

## 2) 构建索引

```bash
source .venv/bin/activate
python -m scripts.build_index --input_dir ./knowledge_base
```

生成内容：

- `data/chroma`
- `data/whoosh`
- `data/processed/chunks.jsonl`

## 3) 自动更新知识库（监听重建）

`watch_docs.py` 会轮询监听目录变化（新增/删除/修改），触发 `build_index` 重建索引。

```bash
source .venv/bin/activate
python -m scripts.watch_docs
python -m scripts.watch_docs --watch "./data/raw,./knowledge_base" --input-dir ./knowledge_base
python -m scripts.watch_docs --interval 3 --debounce-seconds 2 --max-retries 2
```

常用参数：

- `--watch`: 逗号分隔监听目录；默认监听 `RAW_DATA_DIR` 和 `./knowledge_base`
- `--input-dir`: 传给 `build_index` 的源目录（默认 `./knowledge_base`）
- `--interval`: 轮询间隔秒数
- `--debounce-seconds`: 防抖窗口，避免频繁重复触发
- `--max-retries`: 重建失败时自动重试次数
- `--retry-delay-seconds`: 失败重试间隔秒数
- `--no-reset`: 增量追加模式（透传 `build_index --no-reset`）

运维建议：

- watcher 作为独立进程运行，不内嵌进 `start.sh` / `quick_start.sh`
- 线上建议固定监听目录，并配合日志采集观察重建成功率
- 大规模文档变更时，可先暂停 watcher 后手动重建一次，再恢复监听

## 4) 启动服务

### 标准启动

```bash
bash start.sh
bash start.sh --port 9000 --host 0.0.0.0 --no-install --health-retries 30
bash start.sh --no-index --no-reload
bash start.sh --validate-filter-config --smoke
```

### 快速启动（推荐日常）

```bash
bash quick_start.sh
bash quick_start.sh 9000
bash quick_start.sh --port 9000 --host 0.0.0.0 --no-install --no-reload --open-ui
bash quick_start.sh --smoke
bash quick_start.sh --validate-filter-config --smoke
```

`quick_start.sh` 特性：

- 自动创建 `.venv`
- 缺依赖自动安装（可用 `--no-install` 禁用）
- 端口占用自动顺延
- 启动后自动检查后端与 WebUI（失败自动退出）
- 启动时打印 API/health/docs/WebUI 地址
- 支持 `--open-ui` 自动打开浏览器中的 `/ui`
- 支持 `--validate-filter-config` 启动后校验筛选配置文件
- 支持 `--smoke` 启动后自动执行 health/search/chat 冒烟测试

`start.sh` 特性：

- 支持 `--host` / `--no-install` / `--health-retries`
- 支持 `--no-index`（跳过索引构建）
- 支持 `--no-reload`（关闭热重载）
- 支持 `--validate-filter-config`（启动后校验筛选配置）
- 支持 `--smoke` / `--smoke-timeout`（启动后自动冒烟测试）

## 5) 健康检查

```bash
curl http://127.0.0.1:8002/health
```

## 6) Web UI 验证台（小白可用）

后端启动后直接打开：

- `http://127.0.0.1:8002/ui`

可在页面中完成：

- 搜索、聊天、建议词、点击回流
- 检索链路诊断（Query 解析 / 向量召回 / BM25 / 融合排序）
- analytics 趋势查看

当前 Web UI 交互说明：

- 顶部 Tab 切换：`搜索` / `聊天`（默认打开搜索）
- 搜索筛选区采用紧凑横向布局：`排序`、`方向`、`显示数量`、`清空筛选`
- 高级选项支持 URL 参数：`?advanced=1`；新手模式支持 `?simple=1`
- 搜索次级结果区域默认隐藏，仅在有额外结果时展示，避免空白占位
- 标签选中不再在下方重复回显，直接以勾选态作为反馈
- 聊天页顶部支持模式切换：`本地知识库` / `AI大模型`
- 无搜索结果时展示“暂无数据”空态，并提供“切换到本地模型聊天”引导（自动带入当前问题）
- AI 大模型模式支持本地模型下拉（例如 `qwen2.5:7b`），并随请求传递模型参数

### 动态筛选项配置（后台可下发）

前端筛选项由三部分整合生成：

- 知识库关键标签（动态统计）
- 企业开发常用标签（支持配置文件覆盖）
- 自定义标签（管理员配置）

补充说明：

- `General` 标签已从可选项移除（默认语义即通用）
- `/search/filter-options` 返回前会自动清洗并去除 `General`

统一通过 `GET /search/filter-options` 下发，接口会自动去重并合并来源。

如需由管理员自定义选项和顺序，可在以下路径放置配置文件：

- `data/processed/filter_options.json`
- `data/processed/enterprise_tags.json`
- `data/processed/metadata_tag_synonyms.json`（可选：同义词归一映射）

示例模板见：

- `docs/filter_options.example.json`
- `docs/enterprise_tags.example.json`
- `docs/metadata_tag_synonyms.example.json`

可直接复制使用：

```bash
cp docs/filter_options.example.json data/processed/filter_options.json
cp docs/enterprise_tags.example.json data/processed/enterprise_tags.json
cp docs/metadata_tag_synonyms.example.json data/processed/metadata_tag_synonyms.json
```

配置校验（上线前建议执行）：

```bash
source .venv/bin/activate
python -m scripts.validate_filter_config --strict
```

## 7) API 快速示例

### `POST /search`

```json
{
  "query": "Flutter 页面布局怎么写",
  "top_k": 6,
  "offset": 0,
  "sort_by": "score",
  "order": "desc",
  "track_exposure": true,
  "platform": ["Flutter"],
  "module": ["UI"],
  "submodule": ["布局"],
  "type": ["组件"]
}
```

### `POST /chat`

```json
{
  "query": "Flutter 页面布局怎么写",
  "top_k": 6,
  "offset": 0,
  "sort_by": "score",
  "order": "desc",
  "strict_local_kb": true,
  "sources_mode": "brief",
  "model": "qwen2.5:7b",
  "platform": ["Flutter"],
  "module": ["UI"]
}
```

说明：

- `strict_local_kb=true`：强制仅依据知识库回答（适合“本地知识库”模式）
- `model` 可选：指定 Ollama 本地模型（适合“AI大模型”模式）

### `GET /chat/models`

```bash
curl "http://127.0.0.1:8002/chat/models"
```

返回示例：

```json
{
  "current": "qwen2.5:7b",
  "models": ["qwen2.5:7b", "llama3:8b"],
  "available": true
}
```

### `POST /search/suggest`

```json
{
  "prefix": "Flut",
  "limit": 5,
  "platform": ["Flutter"]
}
```

### `POST /search/click`

```json
{
  "chunk_id": "flutter_layout_001_0_abcd1234",
  "amount": 1
}
```

### `GET /search/analytics`

```bash
curl "http://127.0.0.1:8002/search/analytics?limit=10&window=last_7d"
```

### `GET /search/analytics/trend`

```bash
curl "http://127.0.0.1:8002/search/analytics/trend?window=last_7d&granularity=day&fill_empty=true"
```

## 8) 一键自检

```bash
source .venv/bin/activate
python -m scripts.self_check
python -m scripts.self_check --check-ollama --check-api --strict
python -m scripts.self_check --only python,imports,paths --json-line
```

## 9) 冒烟测试（health/search/chat）

```bash
source .venv/bin/activate
python -m scripts.smoke_test --base-url http://127.0.0.1:8002 --strict
```

## 10) 日志维护

```bash
source .venv/bin/activate
python -m scripts.cleanup_analytics_logs --retain-days 30
python -m scripts.cleanup_analytics_logs --retain-days 30 --dry-run
python -m scripts.cleanup_analytics_logs --retain-days 30 --gzip-archive
python -m scripts.cleanup_analytics_logs --retain-days 30 --events click
```

## 11) 测试

```bash
source .venv/bin/activate
pytest -q
```

## 12) 交付流水检查

将 `self_check + build_index + sample_search` 串成可复用流水：

```bash
source .venv/bin/activate
python -m scripts.release_check --strict
python -m scripts.release_check --with-ollama-check --strict
python -m scripts.release_check --allow-empty-search --no-reset-index
```

CI 已内置同款流水：`.github/workflows/release-check.yml`（`push` 到 `main/master` 和 `pull_request` 自动触发），并行执行 `unit-tests` + `release-check`。

## 13) 故障排查速查

- 启动后健康检查失败：先看端口冲突，再执行 `python -m scripts.self_check --check-api --strict`
- `/chat` 报 `LLM unavailable`：执行 `python -m scripts.self_check --check-ollama --strict`
- 本地模型状态异常（127.0.0.1:11434 refused）：先确认 Ollama 服务进程已启动，再执行 `ollama pull qwen2.5:7b`
- 检索无结果：重新执行 `python -m scripts.build_index --input_dir ./knowledge_base`
- analytics 文件增长快：执行 `cleanup_analytics_logs.py` 归档