数据截至 (上游 commit 059ecec2eeac)
txtai — 这是什么 / 全景图 / 阅读地图
30 秒导读： txtai 是一个 all-in-one 的 AI 框架，但本套文档只聚焦它的检索心脏——「嵌入数据库」（embeddings database）：一个把「稠密向量索引 + 稀疏关键词索引 + 关系数据库 + 图网络」四种后端焊在一起的对象，专门服务语义搜索和 RAG（检索增强生成，先查资料再让大模型作答）。
本页是索引页（顶层路由）。 它只覆盖三件事：这是什么、全景怎么转、该往哪读。任何单一机制的原理与代码走读都留给 01–06 章，本页不深入、不与后续重复。
1. 这是什么（零基础也能懂）
一句话定义。 txtai 是一个开源 AI 框架；它对外自称「all-in-one AI framework for semantic search, LLM orchestration and language model workflows」（setup.py:184）。
但本文只讲它的一个部件。 按官方 README 的原话，txtai 最关键的组件是嵌入数据库，它是「向量索引 （稀疏 + 稠密）、图网络、关系数据库的联合体」（README.md 顶部特性段）。搜索、RAG、agent 都建在这块地基上，所以理解 txtai 的检索能力 = 理解嵌入数据库。
它给谁、解决什么问题。 传统搜索按关键词匹配；语义搜索理解意思——查「positive」，能命中「Correct」这种词面不同但含义相近的结果。假设你有一堆文档、图片、音频，想让程序「按意思找」，或想给大模型接一个外部知识源，txtai 就是那层「把数据变成可被意思检索的库」。
它能做什么（本文范围内）：
- 把文本 / 文档 / 图像 / 音频 / 视频转成向量并建索引
- 稠密向量搜索、稀疏关键词搜索、两者混合（hybrid）搜索
- 用 SQL 在向量库上做带过滤条件的检索
- 把结果组织成图网络，跑关系检索与主题建模
用起来什么样。 最小示例来自 README——三行建库、一行搜索：
# 示意（取自 README.md），非源码走读
import txtai
embeddings = txtai.Embeddings() # 用默认句向量模型，零配置
embeddings.index(["Correct", "Not what we hoped"])
embeddings.search("positive", 1)
# [(0, 0.29862046241760254)] # 命中 "Correct"，按语义而非词面
一句话直觉 / 类比。 把嵌入数据库想成一台多引擎的搜索发动机：同一批数据，既能「按意思」查（稠密向量），又能「按词」查（稀疏关键词），还能「带条件」查（SQL），还能「顺着关系」查（图）——而它们共享同一份 id 和内容，所以可以随意组合。这套「可插拔」正是 txtai 的设计取向：setup.py 把 ann / database / graph / scoring / vectors 全部拆成可选依赖分组（setup.py:58-164），你只装用得到的引擎。
本节到此不碰任何底层代码。往下才进入「大盘怎么转」。
2. 全景图（一个 Embeddings 里的『五联合』）
一个 Embeddings 实例（embeddings/base.py:22）就是一个装配现场：它按你的 config，把最多五个协作部件挂到自己身上（__init__ 里的 self.ann / self.scoring / self.database / self.graph / self.model，见 embeddings/base.py:46-65）。README 说的「联合体」，落到代码就是这五个字段。
怎么读下面这张图： 上半是四个数据存储 / 索引后端（查询时被路由到的目标），下半的向量模型是给它们供料的公共上游；中间的 Embeddings 是编排者，谁都不直接对话，全经它转发。
┌──────────────────────────────┐
文档流 documents → │ Embeddings （编排 / 路由） │ ← 查询 query
│ embeddings/base.py:22 │
└───┬────────┬────────┬─────────┘
┌───────────────────┘ │ └───────────────────┐
▼ ▼ ▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐ （content 存哪）
│ ① 稠密索引 │ │ ② 稀疏索引 │ │ ④ 图网络 │ │ ③ 关系数据库│
│ ANN 近邻 │ │ scoring │ │ graph │ │ database │
│ self.ann │ │self.scoring│ │self.graph │ │self.database│
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│「按意思」 │「按词」 │「顺关系」 │「按条件/存原文」
└──────────┬──────┴─────────────┴───────────────┘
▼
┌──────────────────┐
│ ⑤ 向量模型 model │ 文本/文档 → 向量，供 ①②④ 使用
│ self.model │ （VectorsFactory 造）
└──────────────────┘
五个部件一句话职责（谁造它、在哪，详见对应章）：
| # | 部件 | 干什么（白话） | 装配入口（base.py 符号） | 详见章 |
|---|---|---|---|---|
| ① | 稠密索引 ANN | 「按意思找」——近似最近邻搜向量 | createann (:958) | 03 |
| ② | 稀疏索引 scoring | 「按词找」——bm25/tfidf 等关键词打分 | createscoring (:1054) | 03 |
| ③ | 关系数据库 database | 存原文 + 用 SQL 带条件检索（content store） | createdatabase (:972) | 05 |
| ④ | 图网络 graph | 顺着节点关系检索、跑主题建模 | creategraph (:994) | 06 |
| ⑤ | 向量模型 model | 把数据变成向量，喂给 ①②④ | loadvectors (:888) | 02 |
五个部件都可缺席：只挂 ① 就是纯向量库，① + ② 就是 hybrid，③ 决定「结果是
(id, score)元组还是带原文的 dict」。它们如何按 config 被选择性创建，是 01 章的主题。
3. 主线走一遍（高层，不进代码）
嵌入数据库有两条主干路径：建索引（index） 和 搜索（search）。这里只画流向，代码级走读见 01/04 章。
3.1 index 路径：文档流 → 分发 + 向量化 → 建 ANN
入口是 Embeddings.index（embeddings/base.py:103）。它不亲自干活，而是把文档流交给两个助手对象 Stream 和 Transform（embeddings/base.py:117-122），后者一边把原始文档分发进各数据存储，一边向量化：
documents
│
▼ Stream + Transform (index/stream.py:9 · index/transform.py:13)
├─▶ 灌入 database / scoring / graph 的原文与词项 （分发 side）
└─▶ model 向量化 → (ids, dimensions, embeddings) （向量 side）
│
▼ base.py:133-136
createann → ann.index(embeddings) 建稠密索引
│
之后按需依次收尾： ▼ base.py:144-153
scoring.index() → indexes.index() → graph.index()
一个关键时序细节：稀疏 scoring 必须在图之前建好，因为图会用到它——代码里明确注释「This must occur before graph index in order to be available to the graph」（embeddings/base.py:143）。
3.2 search 路径：query → 路由（图 / DB / 向量）→ 融合
入口是 Embeddings.search → batchsearch（embeddings/base.py:356 / :378），真正的调度在 Search.__call__（embeddings/search/base.py:44）。它按「有没有对应部件 + query 长什么样」三选一路由：
query ─▶ Search.__call__ (search/base.py:44)
│
├─ 是图查询？(graph.isquery) ─▶ graphsearch 顺关系找 [06]
│ search/base.py:75-76
├─ 有 database 且非 indexonly？ ─▶ dbsearch SQL+索引 [05]
│ search/base.py:79-80
└─ 否则 ─▶ search() 向量检索 [03/04]
search/base.py:83
│
├─ 只有 ann → 稠密搜索
├─ 只有 scoring → 稀疏搜索
└─ 两者都有 hybrid → Hybrid 融合两路分数
search/base.py:107-119
融合（fusion） 是 hybrid 的精华：稠密与稀疏各取更大候选集（limit*10），再由 Hybrid（embeddings/search/hybrid.py:8）按权重把两套分数合成一套。默认权重 0.5、默认 limit 3（embeddings/search/base.py:63-64）。融合策略细节留给 04 章。
3.3 装配关系概览：configure 与五个 create*
上面所有部件不是在 __init__ 里一次造齐的，而是由 config 驱动、分两个时机装配：
configure（embeddings/base.py:762） ——加载配置时就绪的：词权重 scoring、向量模型 model、query 模型。initindex（embeddings/base.py:786） ——建索引前才创建的：database、（稀疏）scoring、subindexes、graph；ANN 则要等向量算完才createann（base.py:133）。
也就是说 config 里写了 path / content / scoring / graph / indexes 这些键，分别触发 createann / createdatabase / createscoring / creategraph / createindexes（base.py:958–1052）去挂对应部件；什么都不写时 defaults() 会兜底塞一个默认句向量模型 sentence-transformers/all-MiniLM-L6-v2（embeddings/base.py:844）。这条「config → 装配 」链是 01 章的核心。
4. 阅读地图（01–06 每章一句话）
按「由浅入深」建议顺序读；每章都独立带 frontmatter 和代码地图。
| 章 | 文件 | 一句话导航 |
|---|---|---|
| — | index.md（本页） | 这是什么 / 五联合全景 / 两条主线 / 阅读地图 |
| 01 | 01-embeddings-database.md | Embeddings 编排类：config 如何驱动装配，index/upsert/delete/save/load 的完整生命周期 |
| 02 | 02-vectorization.md | 向量化管线：Stream/Transform 与 VectorsFactory，文本/文档/多模态如何变成向量 |
| 03 | 03-indexes-dense-sparse.md | 两类索引后端：稠密 ANN（faiss/hnsw/…）与稀疏 scoring（bm25/tfidf/…）各自怎么建、怎么搜 |
| 04 | 04-search-and-fusion.md | 搜索路由 Search 与混合分数融合 Hybrid：稠密+稀疏如何合成一套排名 |
| 05 | 05-sql-and-database.md | SQL 驱动检索与关系数据库层：content store、dbsearch、带过滤条件的语义查询 |
| 06 | 06-graph.md | 图网络子系统：关系检索、子图、基于社区发现的主题建模 |
怎么用这张地图（给 agent）： 想改「查得准不准」看 03/04；想改「存什么、按什么条件筛」看 05；想「顺着关系/做主题」看 06；想搞清「整台机器怎么被 config 装出来」看 01；想接入新模型/多模态看 02。
5. 巧妙之处速览（精华，细节见各章）
只点「妙在哪」，不展开——展开在对应章。
- 一个对象、五种检索，靠 config 拼装。 没有五个各自为政的类库，只有一个
Embeddings按配置挂载部件（createann/createdatabase/creategraph/createscoring，base.py:958-1073）。用户装什么依赖、写什么 config，就得到什么形态的库——可插拔在架构层就落实了。→ 01 - shortcut 配置自动展开。 写
keyword/sparse/hybrid/graph: true这类简写，defaults()会把它展开成完整 scoring/graph 配置（base.py:833-875），并在 hybrid 时顺手打开 dense。低门槛、少样板。→ 01 - hybrid 先各扩 10 倍候选再融合。 稠密与稀疏各取
limit*10再交给Hybrid合并（search/base.py:108-119），避免任一路早早截断丢掉好结果。→ 04 - content 开关决定返回形态。 有 database 返回带原文的 dict，没有则返回
(id, score)；无 database 时还得自己维护ids映射（base.py:139-140、createids:1016）。一个开关切换两种数据契约。→ 05 - 建索引有严格时序。 scoring 先于 graph、graph 用
Search(indexonly=True)复用向量检索来连边（base.py:143-153）——部件间的依赖被显式排序，不是随手调用。→ 01 / 06
6. 顶层代码地图（导航索引）
顶层跳转表。列真实符号名便于 grep 定位（行号可能随上游漂移，符号名较稳）。逐部件的细粒度代码地图在各章末尾。
| 主题 | 文件路径（相对克隆根 src/python/txtai/） | 符号 |
|---|---|---|
| 编排类本体 | embeddings/base.py | Embeddings |
| 建索引入口 | embeddings/base.py | Embeddings.index |
| 增量写入 / 删除 | embeddings/base.py | Embeddings.upsert · Embeddings.delete |
| 搜索入口 | embeddings/base.py | Embeddings.search · Embeddings.batchsearch |
| config → 装配 | embeddings/base.py | Embeddings.configure · Embeddings.initindex · Embeddings.defaults |
| 五个部件工厂调用 | embeddings/base.py | createann · createdatabase · creategraph · createscoring · loadvectors |
| 落库 + 向量化助手 | embeddings/index/stream.py · embeddings/index/transform.py | Stream · Transform |
| 搜索路由 | embeddings/search/base.py | Search · Search.__call__ · Search.search |
| 混合融合 | embeddings/search/hybrid.py | Hybrid |
| 稠密后端工厂 | ann/dense/factory.py | ANNFactory（faiss/hnsw/annoy/numpy/torch/pgvector/sqlite/…） |
| 稀疏打分工厂 | scoring/factory.py | ScoringFactory（bm25/tfidf/sif/pgtext/sparse） |
| 关系库工厂 | database/factory.py | DatabaseFactory（sqlite/duckdb/client） |
| 图后端工厂 | graph/factory.py | GraphFactory（networkx/rdbms） |
| 向量模型工厂 | vectors/base.py | VectorsFactory |
| 可选依赖分组（可插拔证据） | 克隆根 setup.py | extras（ann/database/graph/scoring/vectors） |
本页是索引页，止于「是什么 / 怎么转 / 去哪读」。任何机制的原理演示、短源码走读、坑与 边界，请进入上表指向的对应章节——本页刻意不与它们重叠。