# 架构决策记录 (ADR)

## ADR-1: 为什么选择 ChromaDB？

**日期**: 2026-07-05 | **状态**: 已采纳

**背景**: 需要一个嵌入式向量数据库来持久化文档嵌入。

**候选**: ChromaDB（嵌入式 SQLite）、Qdrant（独立服务）、FAISS（纯内存）、Milvus（生产级集群）

**决策**: ChromaDB。零运维成本远超吞吐量考量。内置 Collection 概念映射多知识库场景。

**代价**: 高并发下逊于 Qdrant/Milvus。未来可透明迁移（Embedder/Searcher 已隔离 ChromaDB 依赖）。

---

## ADR-2: 为什么默认 bge-small-zh-v1.5？

**日期**: 2026-07-05 | **状态**: 已采纳

**候选**: bge-small-zh-v1.5 (512维/23M)、bge-large-zh-v1.5 (1024维/324M)、text2vec-large-chinese、m3e-base

**决策**: bge-small-zh-v1.5。RTX 4060 上 729 chunks 嵌入仅 1.8s，日常精度足够。高精度场景可切换 large 模型或 OpenAI API。

---

## ADR-3: 为什么采用 Protocol 而非 ABC？

**日期**: 2026-07-05 | **状态**: 已采纳

**候选**: typing.Protocol（结构化子类型）、abc.ABC（名义子类型）、Callable（丢失类型信息）

**决策**: Protocol。外部模块无需依赖本项目源码即可实现 Splitter/Embedder，对插件化友好。

---

## ADR-4: 为什么使用 rank-bm25 而非集成搜索引擎？

**日期**: 2026-07-11 | **状态**: 已采纳

**候选**: rank-bm25（纯 Python BM25）、Elasticsearch（外部服务）、Whoosh（纯 Python 全文搜索）

**决策**: rank-bm25。零运维、轻量、与现有 ChromaDB 架构匹配。在向量候选上做 BM25 重打分（而非全文索引所有文档），兼顾性能和精度。