enterprise-knowledge-assistant

KO | EN

gitlite — search

#javascript #python #hacktoberfest #go #android #rust #linux #docker #macos #nodejs #cli #vue #ios #open-source

enterprise-knowledge-assistant

(★ 9)

Document-scoped enterprise RAG API with FastAPI, SQLite, Qdrant, citations, refusal, and evaluation.

enterprise-knowledge-assistant 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Enterprise Knowledge Assistant（RAG V1 应用 + V2 评测）

一个可运行、可测试、可解释的企业知识库问答后端作品集。它使用
FastAPI 接收 TXT/PDF 文档，将文档切块后写入本地 SQLite 与 Qdrant，
通过 OpenAI embedding 检索证据，并可选择 OpenAI 或 DeepSeek 生成限定
文档范围的回答与结构化引用。

> 当前状态：V1 应用闭环和 V2 评测增强已完成，并增加了轻量 Multi-LLM
> Provider。生产 API
> 保持语义 Dense 检索，Hybrid 仅作为被评测并拒绝上线的实验原型。项目
> 面向本地单用户演示，尚未提供认证、多租户或公网生产部署能力。

## 项目亮点

- 模块化单体：HTTP、业务服务、领域模型、provider 和存储适配器分层。
- 安全摄取：扩展名与媒体类型双重校验、大小限制、安全路径和失败回滚。
- 范围检索：请求必须显式选择文档，检索前后均验证 `document_id`。
- 可信引用：文件名、页码、chunk ID 和分数由应用从真实检索结果构造。
- 隐私边界：不记录问题、文档内容、prompt、回答、向量、密钥或本地路径。
- 可重复评估：10 份合成文档、50 道题；离线门槛不使用 API Key。
- 证据化取舍：参数消融、真实语义对照、阈值扫描、Hybrid负向实验和坏案例目录。
- 性能观测：独立记录本机离线检索与回答编排P50/P95，不冒充线上延迟。
- 自动质量门槛：Ruff、85% 分支覆盖率、全量测试和离线评估进入 CI。
- 多模型后端：OpenAI/DeepSeek 通过同一 `LLMProvider` 接口切换，业务服务
  不依赖具体厂商；在线对比使用相同检索证据、Prompt 和评测问题。

## 架构

```mermaid
flowchart LR
    U["TXT / text PDF"] --> API["FastAPI"]
    API --> ING["IngestionService"]
    ING --> DOC["validate / parse / chunk"]
    ING --> EMB["OpenAI embeddings"]
    ING --> SQL["SQLite document records"]
    EMB --> QD["local Qdrant vectors"]

Q["scoped question"] --> API
    API --> ANS["AnswerService"]
    ANS --> RET["RetrievalService"]
    RET --> EMB
    RET --> QD
    RET -->|"retrieved evidence"| ANS
    ANS --> LLM["OpenAI / DeepSeek Responses API"]
    ANS --> CIT["application-built citations"]
    LLM --> OUT["answer + citations"]
    CIT --> OUT
```

主要数据流是：上传 → 校验 → 解析 → 切块 → embedding → 持久化 →
限定文档检索 → 基于证据回答 → 结构化引用。摄取失败时会补偿删除已经写入的
向量和文件，并保留安全的失败状态记录。

## 快速开始（Windows / Python 3.12）

### 1. 创建项目专用虚拟环境

以下命令只在当前项目创建 `.venv`，不会修改其他课程项目的环境：

```powershell
py -3.12 -m venv .venv
```

### 2. 安装依赖

开发依赖包含运行依赖和 pytest。Qdrant 在 Python 进程内使用本地模式，
不需要另外安装 Docker、Qdrant 客户端、Ollama 或本地模型：

```powershell
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
```

### 3. 配置本地环境

复制安全模板后，在 `.env` 的 `OPENAI_API_KEY=` 后填入自己的 Key。默认
OpenAI 同时负责 embedding 和回答；切换 DeepSeek 回答时再配置
`DEEPSEEK_API_KEY`：

```powershell
Copy-Item .env.example .env
```

`.env` 已被 Git 忽略。不要把 Key 粘贴到聊天、截图、Issue、日志或提交中。
离线测试和评估不需要 Key；上传、检索、回答和 `/health` 完整健康状态需要 Key。

### 4. 先运行质量门槛

此命令依次检查 Ruff lint/格式、带分支覆盖率的测试、依赖完整性、Python
编译和离线 RAG 评估：

```powershell
.\.venv\Scripts\python.exe scripts\check_quality.py
```

成功时最后一行是：

```text
quality_gate_passed=true
```

质量门槛还会检查 Ruff 代码规范与格式，并要求应用分支覆盖率不低于 85%。

### 5. 启动 API

```powershell
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```

看到 Uvicorn 启动信息后，打开 <http://127.0.0.1:8000/docs>。Swagger UI
会展示请求字段和响应模型，适合第一次体验完整流程。

## 五分钟演示流程

1. 调用 `GET /health`；配置有效时返回所有组件状态。
2. 调用 `POST /api/v1/documents`，上传
   `evaluation/documents/access_policy.txt`。
3. 从响应中复制 `document_id`。
4. 调用 `POST /api/v1/answers`，提交下面的 JSON，并替换占位 ID：

```json
{
  "question": "How often is privileged access recertified?",
  "document_ids": ["<DOCUMENT_ID>"],
  "top_k": 5,
  "score_threshold": null
}
```

5. 检查回答中的 `citations`：每条引用都包含真实的文档、chunk、文件名、
   页码（PDF 可用时）、摘要和检索分数。
6. 调用 `DELETE /api/v1/documents/{document_id}` 清理文件、向量和记录。

这个在线演示会调用 OpenAI API 并产生少量费用。若只想验证本地工程链路，
运行离线评估即可。

## API

| 方法与路径 | 作用 |
|---|---|
| `GET /health` | 检查 SQLite、Qdrant、embedding 和 LLM provider |
| `POST /api/v1/documents` | 同步上传并摄取 UTF-8 TXT 或文本型 PDF |
| `GET /api/v1/documents` | 列出不含本地路径的文档元数据 |
| `GET /api/v1/documents/{document_id}` | 获取单个文档记录 |
| `DELETE /api/v1/documents/{document_id}` | 删除文件、向量和文档记录 |
| `POST /api/v1/search` | 在明确选择的文档中检索 Top-K chunks |
| `POST /api/v1/answers` | 返回基于检索证据的回答和结构化引用 |

所有应用错误使用稳定结构，并通过 `X-Request-ID` 关联请求：

```json
{
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "The requested document was not found.",
    "request_id": "..."
  }
}
```

## 配置

所有配置项都记录在 [.env.example](.env.example)。常用项如下：

| 变量 | 默认值 | 说明 |
|---|---|---|
| `OPENAI_API_KEY` | 空 | 在线 embedding 和默认 OpenAI 回答所需，永不提交 |
| `DEEPSEEK_API_KEY` | 空 | 选择 DeepSeek 回答或运行模型对比时所需，永不提交 |
| `RAG_EMBEDDING_MODEL` | `text-embedding-3-small` | 单一 embedding provider |
| `RAG_LLM_PROVIDER` | `openai` | 回答后端：`openai` 或 `deepseek` |
| `RAG_LLM_MODEL` | `gpt-5.6-sol` | 当前回答后端的模型；DeepSeek 使用 `deepseek-v4-flash` |
| `RAG_DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | DeepSeek 官方 OpenAI-compatible API |
| `RAG_QDRANT_PATH` | `data/qdrant` | 本地向量持久化目录 |
| `RAG_SQLITE_PATH` | `data/app.db` | 文档记录数据库 |
| `RAG_MAX_UPLOAD_BYTES` | `10485760` | 单文件最大 10 MiB |
| `RAG_CHUNK_SIZE` | `1000` | chunk 字符目标大小 |
| `RAG_CHUNK_OVERLAP` | `150` | 相邻 chunk 重叠字符数 |
| `RAG_LOG_LEVEL` | `INFO` | `DEBUG/INFO/WARNING/ERROR/CRITICAL` |

## Multi-LLM Backend

项目保留 OpenAI embedding 和 Dense Qdrant 检索，只允许切换最后的回答模型。
DeepSeek 通过现有 `openai` Python SDK 访问官方 Responses API，不需要安装
DeepSeek SDK、Ollama 或本地模型。

默认 OpenAI 回答配置：

```dotenv
RAG_LLM_PROVIDER=openai
RAG_LLM_MODEL=gpt-5.6-sol
RAG_LLM_REASONING_EFFORT=low
```

DeepSeek V4 Flash 回答配置：

```dotenv
RAG_LLM_PROVIDER=deepseek
RAG_LLM_MODEL=deepseek-v4-flash
RAG_LLM_REASONING_EFFORT=none
```

两个后端复用相同的 grounded prompt、无证据标记和应用侧 Citation 构造。
Provider 返回统一的输入、缓存输入、输出和 reasoning token 统计，便于记录
延迟和估算成本。DeepSeek Responses API 当前采用 `deepseek-v4-flash`；旧的
`deepseek-chat`/`deepseek-reasoner` 不作为配置示例。

可选的在线对比会把已跟踪的合成语料发送到 OpenAI 和 DeepSeek，并产生 API
费用，因此必须显式确认：

```powershell
.\.venv\Scripts\python.exe scripts\run_llm_comparison.py --confirm-online
```

对比程序先用 OpenAI embedding 完成一次共享检索，再把完全相同的证据分别
交给两个 LLM。结果包含参考答案 Token F1、回答/拒答行为、引用编号、LLM
延迟、Token usage 和价格快照估算费用，并写入 JSON 与 Markdown 报告。没有
两个 API Key 或没有 `--confirm-online` 时不会发送网络请求。

2026-08-11 使用10份合成文档和50道题完成正式在线对比：

| 指标 | OpenAI `gpt-5.6-sol` | DeepSeek `deepseek-v4-flash` |
|---|---:|---:|
| 参考答案 Token F1 | 75.15% | 72.58% |
| 回答/拒答行为准确率 | 100.00% | 91.67% |
| 引用编号有效率 | 100.00% | 100.00% |
| 应用侧 Citation 完整率 | 100.00% | 100.00% |
| 平均 LLM 延迟 | 1771.45 ms | 912.84 ms |
| P95 LLM 延迟 | 3430.64 ms | 1143.56 ms |
| 估算 API 费用 | $0.106270 | $0.002195 |

结果表明：当前提示词下 OpenAI 的回答/拒答行为更稳定；DeepSeek 平均延迟更低、
估算成本显著更低，但在4道改写或低分证据题上过早拒答。因此默认后端仍保留
OpenAI，DeepSeek 作为可切换的低成本后端，不依据一次小型合成评测宣称模型
整体优劣。完整逐题结果见
[`evaluation/llm_comparison_report.md`](evaluation/llm_comparison_report.md) 和
[`evaluation/llm_comparison_report.json`](evaluation/llm_comparison_report.json)。

## 测试与离线评估

仅运行测试：

```powershell
.\.venv\Scripts\python.exe -m pytest -q -W error
```

最新本地质量门槛为152项自动化测试通过，启用分支统计后的总覆盖率为88.29%，
并持续强制85%的最低覆盖率要求。

仅运行评估：

```powershell
.\.venv\Scripts\python.exe scripts\run_evaluation.py
```

评估集包含 10 份合成文档和 50 道题，覆盖直接命中、多 chunk 证据、文档
范围隔离、不可回答、改写、相似事实干扰、低词法重叠和歧义问题。当前离线
Hashing 基线用于工程回归，不代表线上真实语义效果：

| 指标 | 结果 |
|---|---:|
| Top-5 来源命中率 | 90.00% |
| Evidence Recall@5 | 82.50% |
| MRR | 0.7937 |
| 多 chunk 通过率 | 100% |
| 文档范围隔离 | 100% |
| 不可回答问题拒答率 | 87.50% |
| 引用完整性 | 100% |
| PDF 页码准确率 | 100% |
| 删除一致性 | 通过 |

离线 provider 是确定性的词法 hashing 实现，用来验证工程回归，不冒充真实
OpenAI embedding/LLM 的语义质量。完整方法和逐题结果见
[evaluation/README.md](evaluation/README.md) 与
[evaluation/latest_report.json](evaluation/latest_report.json)。

V2 还包含参数消融、真实语义 Embedding 对照、阈值扫描和 Hybrid
（Dense + BM25 + RRF）离线原型。当前 Hybrid Hashing 对照没有提升
Evidence Recall@5，也没有减少检索失败案例；虽然 MRR 小幅增加 0.0063，
仍不足以修改生产检索策略。进一步使用真实语义 Embedding 对照后，Hybrid
Recall 从 100% 降至 92.50%，MRR 从 0.9833 降至 0.8438，并新增3个检索
失败案例，因此当前明确保留 Dense 检索。完整实验边界与结果见
[evaluation/README.md](evaluation/README.md)。

本地离线性能基准使用135个预热后样本：检索P50/P95约为
`7.64/7.93 ms`，完整回答编排约为`7.60/7.97 ms`。这些数字只描述当前
机器上的Hashing、临时本地Qdrant/SQLite和合成语料，不代表OpenAI网络
延迟或生产并发能力。已知失败按检索、阈值、回答策略和排序阶段记录在
`evaluation/bad_case_report.json`。

## 项目结构

```text
app/api                 HTTP 路由和依赖解析
app/core                类型化配置、日志、异常和错误处理
app/document_processing 文件校验、持久化、TXT/PDF 解析和切块
app/domain              框架无关的文档、chunk、检索和引用模型
app/providers           OpenAI embedding/LLM 接口与适配器
app/services            摄取、检索、回答和文档生命周期
app/storage             SQLite repository 与本地 Qdrant adapter
.github/workflows       独立仓库的 GitHub Actions 质量门槛
evaluation              可重复语料、问题、provider 和评估报告
scripts                 语料生成、评估和质量门槛入口
tests                   单元、集成和评估测试
data                    被 Git 忽略的本地运行数据
docs                    调研、架构、provider 和发布记录
```

## 安全与限制

- 只绑定 `127.0.0.1`；不要直接暴露到公网或共享网络。
- V1 没有身份认证、权限控制、多租户隔离、限流或生产密钥管理。
- 只支持 UTF-8 TXT 和文本型 PDF；扫描件与 OCR 明确不支持。
- SQLite 和 Qdrant local 适合小型本地数据集，不是大规模生产方案。
- LLM 请求不启用持久会话、工具或 Web 搜索；DeepSeek/OpenAI Key 均只从
  本地环境读取。
- 模型可能出错；结构化引用可追溯来源，但不等于事实保证。

更多安全说明见 [SECURITY.md](SECURITY.md)。

## 许可证

项目使用 [MIT License](LICENSE)。可以在保留版权和许可声明的前提下使用、
修改和分发；软件按原样提供，不附带担保。

## 设计依据

- [docs/architecture_log.md](docs/architecture_log.md)：V1 架构决策和质量边界。
- [docs/open_source_research.md](docs/open_source_research.md)：四个开源项目的调研证据。
- [docs/provider_decisions.md](docs/provider_decisions.md)：OpenAI provider 与隐私配置。
- [docs/mvp_scope.md](docs/mvp_scope.md)：最终 V1 范围与验收状态。
- [docs/release_checklist.md](docs/release_checklist.md)：发布前证据清单。

enterprise-knowledge-assistant

enterprise-knowledge-assistant 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

enterprise-knowledge-assistant

enterprise-knowledge-assistant 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README