qmd开发者指南：从源码到部署，构建本地化SOTA搜索引擎

【免费下载链接】qmd mini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local 项目地址: https://gitcode.com/gh_mirrors/qmd1/qmd

qmd是一款本地化的轻量级命令行搜索引擎，专为文档、知识库和会议记录等内容打造。它跟踪当前最先进的搜索技术，同时保持完全本地运行的特性，让你在保护数据隐私的同时享受高效的搜索体验。

一、项目概述：认识qmd的核心优势

qmd作为一款本地化搜索引擎，具备以下核心特点：

• 完全本地运行：所有数据处理和搜索操作均在本地完成，无需担心数据泄露
• 先进搜索技术：融合向量搜索、BM25算法和LLM重排序等SOTA技术
• 轻量级CLI工具：简洁高效的命令行界面，易于集成到各种工作流中
• 灵活扩展性：支持自定义数据集和模型调优，满足个性化需求

二、架构解析：qmd的工作原理

qmd的搜索流程主要分为四个关键阶段，构成了一个高效的搜索引擎架构：

2.1 查询扩展模块

用户查询首先进入查询扩展模块，该模块使用Qwen3 1.7B模型结合LoRA技术，通过以下方式增强查询：

• HyDE技术：生成假设性文档片段，增强查询语义理解
• 向量检索：将查询转换为向量表示，捕捉语义信息
• 关键词提取：生成BM25算法所需的关键词

2.2 并行搜索模块

扩展后的查询被分发到多个并行搜索组件：

• 向量搜索：利用向量相似性查找相关文档
• BM25搜索：基于关键词匹配的传统搜索方法

这种多策略并行搜索确保了结果的多样性和全面性。

2.3 结果融合与重排序

多个搜索结果通过以下步骤进行优化：

• ** reciprocal Rank Fusion**：融合不同搜索策略的结果
• LLM重排序：使用本地LLM对结果进行智能排序，提升相关性

三、环境准备：搭建开发环境

3.1 克隆代码仓库

首先，克隆qmd项目仓库到本地：

git clone https://gitcode.com/gh_mirrors/qmd1/qmd
cd qmd

3.2 安装依赖

项目使用uv作为Python包管理器，安装依赖：

cd finetune
uv install

对于TypeScript部分，使用bun安装依赖：

bun install

四、数据准备：构建你的知识库

4.1 数据集结构

qmd支持多种格式的数据集，主要数据文件位于finetune/data/目录下，包括：

• qmd_expansion_balanced_deduped.jsonl：平衡去重的扩展数据集
• qmd_expansion_handcrafted.jsonl：手工制作的扩展数据集
• qmd_only_sampled.jsonl：仅包含qmd样本的数据集

4.2 数据预处理

使用提供的工具脚本进行数据准备：

cd finetune/dataset
python prepare_data.py

该脚本会对原始数据进行清洗、格式化和验证，确保符合模型训练要求。

五、模型训练：微调你的搜索引擎

5.1 配置训练参数

训练配置文件位于finetune/configs/目录，主要配置文件包括：

• sft.yaml：标准微调配置
• sft_local.yaml：本地微调配置
• accelerate_multi_gpu.yaml：多GPU加速配置

5.2 开始训练

使用以下命令启动模型训练：

cd finetune
python train.py --config configs/sft.yaml

训练过程中，模型会保存在finetune/experiments/目录下，你可以根据需要调整训练参数以获得最佳性能。

六、部署与使用：本地搜索引擎实战

6.1 模型转换

训练完成后，将模型转换为可用格式：

cd finetune
python convert_gguf.py

6.2 启动搜索服务

使用以下命令启动qmd搜索服务：

bun run src/cli/qmd.ts

6.3 基本搜索命令

使用qmd进行搜索的基本命令格式：

qmd search "你的搜索查询"

七、高级功能：定制你的搜索体验

7.1 技能扩展

qmd支持通过技能扩展增强搜索能力，相关代码位于skills/qmd/目录。你可以根据需要添加自定义技能，扩展搜索引擎功能。

7.2 性能优化

通过修改配置文件和调整模型参数，可以优化搜索性能。关键优化点包括：

• 调整向量搜索维度
• 优化BM25参数
• 调整重排序策略

八、测试与评估：确保搜索质量

qmd提供了全面的测试工具，位于test/目录，包括：

• cli.test.ts：命令行界面测试
• eval.test.ts：搜索评估测试
• store.test.ts：存储系统测试

运行测试命令：

bun test

九、总结：开启你的本地化搜索之旅

qmd作为一款本地化SOTA搜索引擎，为开发者提供了构建个人知识库搜索系统的完整解决方案。通过本文介绍的步骤，你可以从源码开始，构建一个功能强大的本地搜索引擎，保护数据隐私的同时享受高效的搜索体验。

无论是个人知识管理还是企业文档检索，qmd都能为你提供快速、准确的搜索服务，让你轻松掌控自己的数据和知识。

【免费下载链接】qmd mini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local 项目地址: https://gitcode.com/gh_mirrors/qmd1/qmd