LLMWare FAQ 深度解读：分块大小、向量库、Collection 存储与模型配置的源码级实操指南

LLMWare FAQ 深度解读分块大小、向量库、Collection 存储与模型配置的源码级实操指南【免费下载链接】llmwareUnified framework for building enterprise RAG pipelines with small, specialized models项目地址: https://gitcode.com/GitHub_Trending/ll/llmware本文以 LLMWare 官方 FAQ 文档docs/community/faq.md为主线系统回答六个高频使用问题如何设置分块大小chunk_size / max_chunk_size、如何选择嵌入向量库vector_db、如何切换 Collection 存储MongoDB / Postgres / SQLite、如何通过 result_count 获取更多检索上下文、如何更换生成式 LLM 与嵌入模型以及 Google Colab 下模型运行缓慢的解决方法。文中每一项参数说明均对照 llmware/library.py、llmware/configs.py、llmware/retrieval.py 等源码实现进行了佐证帮助读者从会用参数进阶到理解参数在底层如何生效。1. 如何设置分块大小chunk_size 与 max_chunk_size核心问题我想把文档解析成更小的块。LLMWare 通过Library类的add_files方法暴露两个分块控制参数chunk_size目标分块大小默认 400max_chunk_size分块大小上限默认 600。从源码结构看这两个参数会原样传递给Parser类。在 library.py 中add_files的方法签名为def add_files(self, input_folder_pathNone, encodingutf-8, chunk_size400, get_imagesTrue, get_tablesTrue, smart_chunking1, max_chunk_size600, table_gridTrue, get_header_textTrue, table_strategy1, strip_headerFalse, verbose_level2, copy_files_to_libraryTrue, set_custom_logging-1, use_logging_fileFalse):方法内部随后在 library.py 构造Parser(libraryself, chunk_sizechunk_size, max_chunk_sizemax_chunk_size, ...)并调用ingest(...)也就是说分块行为完全由解析阶段决定解析完成后还会调用CollectionWriter.build_text_index()重建文本索引。此外add_files返回的output_results字典包含docs_added、blocks_added等计数可用于验证不同 chunk_size 下产生的块数差异。官方 FAQ 的完整示例——将同一批文件以不同分块大小分别加入同一个库from pathlib import Path from llmware.library import Library path_to_my_library_files Path(~/llmware_data/sample_files/Agreements) my_library Library().create_new_library(library_namechunk_size_example) my_library.add_files(input_folder_pathpath_to_my_library_files, chunk_size400) my_library.add_files(input_folder_pathpath_to_my_library_files, chunk_size600)需要注意add_files默认执行重复检查dupe_checkTrue以不同 chunk_size 重复添加同一批文件时实际入库行为受解析与去重逻辑影响建议通过返回的docs_added/blocks_added计数确认每次添加的实际效果。2. 如何设置嵌入向量库vector_db核心问题我想使用某个特定的 embedding store。为某个库构建嵌入时Library的install_new_embedding方法通过vector_db参数指定向量存储。从源码看该方法签名为见 library.pydef install_new_embedding(self, embedding_model_nameNone, vector_dbNone, from_hfFalse, from_sentence_transformerFalse, modelNone, tokenizerNone, model_api_keyNone, vector_db_api_keyNone, batch_size500, max_lenNone, use_gpuTrue):其关键行为有三点不传vector_db时的回退逻辑方法内部若vector_db为空会读取全局默认值LLMWareConfig().get_config(vector_db)见 library.py。在 configs.py 中默认配置为vector_db: milvus。合法性校验所选向量库必须出现在支持列表中否则抛出LLMWareException见 library.py。实际写入加载模型后通过EmbeddingHandler(self).create_new_embedding(vector_db, my_model, batch_sizebatch_size)路由到对应向量库的资源层完成写入。当前仓库支持的向量库清单定义在 configs.py_supported {vector_db: [chromadb, neo4j, milvus, pg_vector, postgres, redis, pinecone, faiss, qdrant, mongo_atlas, lancedb], ...}源码中还有一条注释值得注意configs.pypostgres与pg_vector是同一后端的两个别名。可用LLMWareConfig().get_supported_vector_db()动态查询避免硬编码。FAQ 的完整示例——对同一份数据构建三套嵌入并存入三种不同的向量库import logging from pathlib import Path from llmware.configs import LLMWareConfig from llmware.library import Library logging.info(fCurrently supported embedding stores: {LLMWareConfig().get_supported_vector_db()}) library Library().create_new_library(library_nameembedding_store_example) library.add_files(input_folder_pathPath(~/llmware_data/sample_files/Agreements)) library.install_new_embedding(vector_dbpg_vector) library.install_new_embedding(vector_dbmilvus) library.install_new_embedding(vector_dbfaiss)原 FAQ 中参数名误写为input_foler_path此处已按 library.py 的实际签名修正为input_folder_path。3. 如何设置 Collection 存储set_active_db核心问题我想使用某个特定的 collection store。Collection 存储保存的是库的文本块集合text collections它与向量库相互独立。切换入口是LLMWareConfig类的set_active_db方法见 configs.pyclassmethod def set_active_db(cls, new_db): Sets the default database for Library text collections if new_db in cls._supported[collection_db]: cls._conf[collection_db] new_db else: raise LLMWareException(messagefLLMWareConfig - set_active_db - selected fdb is not supported - {new_db})从源码结构看当前支持的 Collection 存储为三种configs.pymongo、postgres、sqlite自 0.4.0 版本起默认值为sqlite见 configs.py 中collection_db: sqlite及注释# change 0.4.0: default collection_db set to sqlite。查询当前值用get_active_db()查询支持清单用get_supported_collection_db()。FAQ 的完整示例——打印当前值、打印支持清单、然后切换到 Postgresimport logging from llmware.configs import LLMWareConfig logging.info(fCurrently active collection store: {LLMWareConfig.get_active_db()}) logging.info(fCurrently supported collection stores: {LLMWareConfig().get_supported_collection_db()}) LLMWareConfig.set_active_db(postgres) logging.info(fCurrently active collection store: {LLMWareConfig.get_active_db()})注意get_active_db与set_active_db都是类方法通过类名直接调用LLMWareConfig.get_active_db()或通过实例调用均可。4. 如何检索到更多上下文result_count核心问题我想从一次查询中检索到更多上下文。LLMWare 的Query类llmware/retrieval.py提供三个主查询方法query、text_query、semantic_query三者均接受result_count参数默认值均为 20见 retrieval.py 与 retrieval.py。其中query是text_query与semantic_query的统一包装入口依据query_type参数路由到具体实现见 retrieval.py。增大result_count即增大返回结果数量从而扩大送入下游模型的上下文规模。底层原理以 pgvector 为例最为直观result_count最终会成为 SQL 语句中LIMIT关键字之后的取值。在 embeddings.py 的search_index方法中语义检索的 SQL 模板为q (fSELECT id, block_mongo_id, embedding - %s AS distance, text fFROM {self.collection_name} ORDER BY distance LIMIT %s)其中-是 pgvector 的欧氏距离运算符。当result_count10、集合名为agreements、查询向量为[1, 2, 3]时展开后的等价 SQL 即 FAQ 中展示的样子SELECT id, block_mongo_id, embedding - [1, 2, 3] AS distance, text FROM agreements ORDER BY distance LIMIT 10;FAQ 的完整示例——对同一库执行两次相同查询仅将结果数从 3 调到 6import logging from pathlib import Path from llmware.configs import LLMWareConfig from llmware.library import Library from llmware.retrieval import Query logging.info(fCurrently supported embedding stores: {LLMWareConfig().get_supported_vector_db()}) library Library().create_new_library(library_namecontext_size_example) library.add_files(input_folder_pathPath(~/llmware_data/sample_files/Agreements)) library.install_new_embedding(vector_dbpg_vector) query Query(library) query_results query.semantic_query(querysalary, result_count3, results_onlyTrue) logging.info(fNumber of results: {len(query_results)}) query_results query.semantic_query(querysalary, result_count6, results_onlyTrue) logging.info(fNumber of results: {len(query_results)})semantic_query还有一个可选的embedding_distance_threshold参数可用于按距离阈值过滤结果见 retrieval.py可与result_count配合使用在扩大上下文的同时控制召回质量。5. 如何更换大语言模型gen_model核心问题我想使用不同的 LLM。入口是Prompt类的load_model方法其gen_model参数指定模型名见 prompts.pydef load_model(self, gen_model, api_keyNone, from_hfFalse, trust_remote_codeFalse, ...): ... self.llm_model self.model_catalog.load_model(gen_model, api_keyself.llm_model_api_key, ...)从源码结构看gen_model会被透传给ModelCatalog.load_modelmodels.py由模型目录统一解析该模型来自本地还是 HuggingFace 等来源并完成加载。ModelCatalog还提供三个清单方法便于在写代码前枚举可用模型list_generative_models()列出全部生成式模型models.pylist_generative_local_models()仅列出本地可运行的模型models.pylist_open_source_models()仅列出开源模型models.py。FAQ 的完整示例——打印三类模型清单并用 BLING 系列模型分别创建三个 prompterimport logging from llmware.models import ModelCatalog from llmware.prompts import Prompt llm_gen ModelCatalog().list_generative_models() logging.info(fList of all LLMs: {llm_gen}) llm_gen_local ModelCatalog().list_generative_local_models() logging.info(fList of all local LLMs: {llm_gen_local}) llm_gen_open_source ModelCatalog().list_open_source_models() logging.info(fList of all open source LLMs: {llm_gen_open_source}) prompter_bling_1b Prompt().load_model(gen_modelllmware/bling-1b-0.1) prompter_bling_tiny_llama Prompt().load_model(gen_modelllmware/bling-tiny-llama-v0) prompter_bling_falcon_1b Prompt().load_model(gen_modelllmware/bling-falcon-1b-0.1)原 FAQ 中日志语句误将变量写作llm_local此处已统一为llm_gen_local。6. 如何更换嵌入模型embedding_model_name核心问题我想使用不同的 embedding model。嵌入模型同样通过install_new_embedding的embedding_model_name参数指定见 library.py。源码中该方法对模型的加载分三条路径传入embedding_model_name时走ModelCatalog().load_model(selected_modelembedding_model_name, api_keymodel_api_key)从模型目录查找并加载传入已实例化的model且from_hfTrue时走ModelCatalog().load_hf_embedding_model(model, tokenizer)此时batch_size会被强制调整为 50library.py传入model且from_sentence_transformerTrue时必须同时提供embedding_model_name否则抛出LLMWareExceptionlibrary.py。可用嵌入模型清单通过ModelCatalog().list_embedding_models()获取models.py。FAQ 的示例意图是列出全部嵌入模型然后用mini-lm-sber与industry-bert-contracts两个模型对同一库各构建一次嵌入。按当前仓库 API 整理后的可运行版本如下import logging from pathlib import Path from llmware.models import ModelCatalog from llmware.library import Library # 原 FAQ 误用了 list_generative_models正确方法为 list_embedding_models embedding_models ModelCatalog().list_embedding_models() logging.info(fList of embedding models: {embedding_models}) library Library().create_new_library(library_nameembedding_models_example) library.add_files(input_folder_pathPath(~/llmware_data/sample_files/Agreements)) library.install_new_embedding(embedding_model_namemini-lm-sber) library.install_new_embedding(embedding_model_nameindustry-bert-contracts)同一库可以用不同嵌入模型重复调用install_new_embedding每套嵌入独立存储便于后续对比不同模型的检索效果。7. 为什么模型在 Google Colab 中运行缓慢FAQ 给出的解释LLMWare 的模型设计为至少需要 16GB 内存运行而 Colab 默认仅提供约 13GB 内存会显著拖慢计算速度。建议在 Colab 中启用 T4 GPU以获得包括 16GB 内存在内的额外资源使模型流畅运行。启用 T4 GPU 的步骤在 Colab 笔记本中点击 Runtime运行时标签选择 Change runtime type更改运行时类型在 Hardware Accelerator硬件加速器下选择 T4 GPU。注意免费使用 T4 存在每周用量上限。此外结合上文第 5、6 节可知load_model与install_new_embedding均默认use_gpuTrue因此在启用 GPU 后无需额外改动代码即可利用加速。参考路径汇总主题关键文件与方法分块参数library.pyadd_files向量库选择library.pyinstall_new_embeddingconfigs.py支持清单Collection 存储configs.pyget_active_db/set_active_db/get_supported_collection_db检索上下文retrieval.pyquery/text_query/semantic_queryembeddings.pypgvector SQL 模板模型选择prompts.pyPrompt.load_modelmodels.pyModelCatalog 清单方法原始 FAQdocs/community/faq.md以上各小节的参数默认值、支持清单与回退逻辑均以当前仓库源码为准由于 LLMWare 持续迭代若升级版本后行为有出入建议以get_supported_vector_db()、get_supported_collection_db()等运行时查询接口返回的结果为最终依据。【免费下载链接】llmwareUnified framework for building enterprise RAG pipelines with small, specialized models项目地址: https://gitcode.com/GitHub_Trending/ll/llmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考