数据截至 (上游 commit 081bc084a5bc)
LLMWare —— 总览:这是什么 / 全景图 / 主线 / 阅读地图
30 秒导读: LLMWare 是一个本地优先的 RAG(检索增强生成,Retrieval-Augmented Generation)框架,给"有一堆企业文档、想让小模型基于这些文档准确回答问题"的场景用。 本套文档只讲它两大件里的一件——RAG 流水线(rag-retrieval 这条线), 追一份 PDF 从入库到被当证据回答问题的全过程。
1. LLMWare 是什么(零基础也能懂)
一句话定义: LLMWare 是一个把"文档知识"接到"生成式 AI 模型"的中间件(middleware), 让你在自己的笔记本 / 边缘设备上,就能搭出一个基于私有文档回答问题的知识库应用。
这不是我的概括,是它自己写的定位:
"The llmware package aspires to be a middleware in LLM applications ... it provides the infrastructure between the components, such as the models, the prompts, the text databases, and the vector databases." ——
llmware/__init__.py:18-21
它有两大组件(据 README.md:11-17 的『two main components』段落):
| 组件 | 干什么 | 本套文档 是否覆盖 |
|---|---|---|
| Model catalog(模型目录) | 300+ 预打包量化模型 + 50+ 自研 RAG 小模型(SLIM/Bling/Dragon),统一 ModelCatalog 查找加载 | 否(不是本套主题) |
| RAG Pipeline(RAG 流水线) | 文档解析、入库、建知识库、嵌入、检索、带源提示的全生命周期组件 | 是(本套 01–05 章) |
本套文档聚焦第二件:RAG 流水线(area: rag-retrieval)。 模型目录那条线是另一个主题,这里不展开。
给谁用、解决什么问题
设想你在一家公司,手里有几百份 PDF 合同、财报、HR 政策。你想问:"这份发票总额是多少?" 而且要求:(1) 答案必须基于这些文档、不能瞎编;(2) 数据不上云、跑在本地。 LLMWare 就是把这套流程标准化的工具箱——你只需把文件夹指给它,剩下的解析、切块、嵌入、 检索、组装提示,它都有现成部件。
用起来什么样(最小真实示例)
下面这段直接摘自 README(README.md:65-83),是入库知识库的最短路径:
from llmware.library import Library
# 1. 建一个 library —— 知识库容器
lib = Library().create_new_library("my_library")
# 2. add_files 是万能入库函数:指向一个文件夹,混合格式都行
# 文件 按扩展名路由到对应解析器,解析、切块、索引进文本集合 DB
lib.add_files("/folder/path/to/my/files")
# 3. 给这个 library 装一个嵌入(挑一个嵌入模型 + 一个向量库)
lib.install_new_embedding(embedding_model_name="mini-lm-sbert", vector_db="milvus", batch_size=500)
一句话直觉: 把 Library 当成一个带索引的文件柜——add_files 是把文件塞进去并
自动贴好标签(文本集合 DB),install_new_embedding 是再给每页内容按"语义相似度"排一遍座(向量库),
之后 Query 就能又快又准地把相关那几页翻出来。
本节不出现底层代码细节;目标是让你先知道"这东西是干嘛的"。下钻实现请沿阅读地图往后走。
2. 顶层全景(它大概怎么转)
怎么读这张图
从左到右是数据流:一份文件进来,被解析成一个个文本块(block),落进两类存储, 再被嵌入、被查询、最后组装成给模型的提示。注意底部两类存储分家—— 文本和元数据进"文本集合 DB",原始文件和抽出来的图片进"文件资源目录"。
┌─────────────────────────────────────────────────────────┐
一个文件夹 │ RAG 流水线 │
(PDF/DOCX/…) │ │
│ │ add_files │
└──────────►│ (按扩展名路由) │
│ │ │
│ ▼ │
│ ┌────────┐ 一块块 block ┌──────────────────┐ │
│ │ Parser │ ───────────────► │ 文本集合 DB │ │
│ │ 解析+ │ │ (mongo/pg/sqlite)│ │
│ │ 分块 │ │ 文本+元数据 │ │
│ └───┬────┘ └────────┬─────────┘ │
│ │ 原始文件/抽出的图片 │ │
│ ▼ │ 取文本 │
│ ┌────────────────┐ ▼ │
│ │ 文件资源目录 │ ┌──────────────┐ │
│ │ llmware_data/ │ │ Embedding │ │
│ │ accounts/{lib}/ │ │ Handler │ │
│ │ uploads,images │ │ (向量化) │ │
│ └────────────────┘ └──────┬───────┘ │
│ ▼ │
│ ┌───── ─────────┐ │
│ │ 向量库 │ │
│ │ (milvus/faiss │ │
│ │ /chroma…) │ │
│ └──────┬───────┘ │
│ │ │
│ 用户提问 ──► ┌────────┐ 文本/语义/双通道 │ │
│ │ Query │◄────────────────┘ │
│ └───┬────┘ │
│ │ 命中的 block(证据) │
│ ▼ │
│ ┌────────┐ 带源提示 ┌─────────┐ │
│ │ Prompt │ ───────────► │ LLM │──►答案 │
│ │ 打包+ │ │ 推理 │ +核查 │
│ │ 核查 │◄──────────── └─────────┘ │
│ └────────┘ evidence_check │
└─────────────────────────────────────────────────────────┘
部件一句话职责
| 部件 | 一句话职责 | 在哪个文件(符号) |
|---|---|---|
Library | 知识库容器:建库、add_files 入库、装嵌入、发库卡,统管双存储 | llmware/library.py:38 class Library |
Parser | 按文件类型解析并切成文本块(block),写进文本集合 DB | llmware/parsers.py:60 class Parser |
EmbeddingHandler | 嵌入总控:把 block 向量化并路由到选中的向量库,做增量同步 | llmware/embeddings.py:78 class EmbeddingHandler |
Query | 检索引擎:文本 / 语义 / 双通道查询,把命中的 block 取回 | llmware/retrieval.py:43 class Query |
Prompt | 把检索到的 block 打包成"带源上下文"喂给模型,并做事后核查 | llmware/prompts.py:44 class Prompt |
两类存储(容易混,先分清)
据 LLMWareConfig._supported(llmware/configs.py:84-86),LLMWare 的存储分三档,
本套主要涉及前两档:
- 文本集合 DB(collection_db) —— 存文本块与元数据,可选
mongo/postgres/sqlite。 - 向量库(vector_db) —— 存嵌入向量,可选 11 种(见 §第 03 章)。
- 文件资源目录 —— 磁盘上的
llmware_data/accounts/{account}/{library_name}/, 下有uploads(原始文件副本)、images(抽出的图)等子目录 (llmware/library.py:171-180)。
3. 主线走一遍:一份 PDF 从入库到被当证据回答
下面是端到端的高层路径(不进代码,只讲发生了什么;每一步都对应后面某一章)。
① 建库。 Library().create_new_library("my_library") 建好知识库容器,
同时在磁盘上开好 llmware_data/accounts/.../my_library/ 目录树
(llmware/library.py:109、:171-188)。 → 详见 01 章
② 入库 + 解析分块。 lib.add_files("/folder/")(llmware/library.py:516)扫描文件夹,
把每个文件按扩展名路由到对应解析器。PDF 走 Parser.parse_pdf
(llmware/parsers.py:672),把每页内容切成一个个 block(带文本、页码、来源文件名等元数据),
写进文本集合 DB;原始 PDF 副本进 uploads/,抽出的图进 images/。
→ 详见 02 章
③ 嵌入。 lib.install_new_embedding(...)(llmware/library.py:783)调
EmbeddingHandler.create_new_embedding(llmware/embeddings.py:104),
把库里的 block 逐批向量化,写进你选的向量库(如 milvus)。
→ 详见 03 章
④ 检索。 用户问"这份发票总额是多少?"。Query(lib).semantic_query(...)
(llmware/retrieval.py:706)把问题也嵌成向量,经
EmbeddingHandler.search_index(llmware/embeddings.py:129)在向量库里找最相似的 block;
也可用 text_query(:421)做关键词 匹配,或 dual_pass_query(:865)双通道融合。
命中的 block 就是候选证据。 → 详见 04 章
⑤ 打包成带源提示 + 回答 + 核查。 Prompt.add_source_query_results(results)
(llmware/prompts.py:374)把命中的 block 打包成"model-ready"上下文(必要时分批以适配上下文窗口),
prompt_with_source(...)(:563)带着这些证据让本地小模型作答,
最后 evidence_check_sources(...)(:1141)做事后核查——回答里的说法能不能在源证据里找到。
→ 详见 05 章
一句话收束:文件进 → 变 block → 进双存储 → 嵌入 → 查回证据 → 带源作答 → 核查。 这条线就是本套文档要逐层讲透的东西。
4. 阅读地图(建议按序读)
由浅入深,五章顺着上面主线的顺序排:
| 章 | 讲什么 | 何时读 |
|---|---|---|
| 01 库与存储 | Library 这个知识库容器怎么工作、文本集合 DB 与文件资源目录这套双存储底座 | 想先搞懂"知识库到底是什么、数据存哪" |
| 02 解析与分块 | 多格式解析、按扩展名路由、文本分块——block 数据模型是怎么诞生的 | 想知道"一份 PDF 怎么变成可检索的小块" |
| 03 嵌入与向量库 | EmbeddingHandler 一套接口如何收编 11 种向量库、增量同步 | 想理解"语义检索的底座怎么搭、怎么换向量库" |
| 04 检索引擎 | Query 的文本查询、语义查询、双通道查询 | 想知道"提问后系统怎么把相关内容捞回来" |
| 05 生成与证据 | 证据打包、带源提示、事后核查 | 想看"检索结果怎么变成一个有据可查的回答" |
5. 全库代码地图(导航索引)
三列表:主题 → 文件 → 真实符号名。符号名比行号抗漂移,可直接在克隆里 grep 定位。
| 主题 | 文件 | 关键符号 |
|---|---|---|
| 包定位 / 版本 | llmware/__init__.py | 模块 docstring、__version__(0.4.6) |
| 知识库容器 | llmware/library.py | Library、create_new_library、load_library、get_library_card |
| 入库 / 装嵌入 | llmware/library.py | Library.add_files、Library.install_new_embedding |
| 库目录管理 | llmware/library.py | LibraryCatalog、get_library_card、create_new_library_card |
| 解析总入口 | llmware/parsers.py | Parser、parse_one、parse_one_office、parse_one_pdf |
| PDF / Office 解析 | llmware/parsers.py | Parser.parse_pdf、Parser.parse_office、parse_pdf_by_ocr_images |
| 文本集合读写 | llmware/resources.py | CollectionRetrieval、CollectionWriter |
| 嵌入总控 | llmware/embeddings.py | EmbeddingHandler、create_new_embedding、search_index |
| 各向量库实现 | llmware/embeddings.py | EmbeddingMilvus、EmbeddingFAISS、EmbeddingChromaDB、EmbeddingPGVector、EmbeddingQdrant、EmbeddingRedis、EmbeddingLanceDB、EmbeddingPinecone、EmbeddingMongoAtlas、EmbeddingNeo4j |
| 向量库注册表 | llmware/configs.py | VectorDBRegistry、vector_db_list、get_vector_db_list、add_vector_db |
| 存储后端配置 | llmware/configs.py | LLMWareConfig._supported(collection_db / vector_db / table_db) |
| 检索引擎 | llmware/retrieval.py | Query、text_query、semantic_query、dual_pass_query、text_query_with_document_filter |
| 带源提示 | llmware/prompts.py | Prompt、add_source_query_results、add_source_new_query、add_source_document |
| 生成 / 核查 | llmware/prompts.py | Prompt.prompt_with_source、Prompt.evidence_check_sources |
说明:本章只画"大盘",不深入任何单模块实现——每个部件的原理与源码走读在 对应的 01–05 章。引用均 as-of
sourceCommit081bc08。