English | 中文
“您是否曾被淹没在海量的本地文档中，为了查找一个信息而焦头烂额？您是否担心将敏感文件上传到云端会带来隐私风险？”
zhzAI 智能助理 就是为解决这些痛点而生。它是一个完全在您自己电脑上运行的、安全的、聪明的“专属本地大脑”。它能深度阅读和理解您指定的文件夹中的所有文档，并用最自然的方式与您对话，帮助您快速找到所需信息，完成工作任务。
zhzAI 旨在构建一个完全运行于用户本地环境、无需云端依赖的下一代知识管理与交互系统。我们的架构设计遵循三大核心原则：
- 🔒 数据主权 (Data Sovereignty): 您的任何文档、查询、交互记录都永不离开本地设备，从根本上杜绝云端数据泄露的风险。完全离线可用。
- ⚡ 极致性能 (Peak Performance): 通过软硬件协同优化（HAL），充分利用现代PC的CPU与GPU异构计算能力，实现低延迟、高吞吐的实时交互。即使是普通办公电脑也能流畅运行。
- 🧠 智能涌现 (Emergent Intelligence): 我们相信，真正的智能并非单一算法的胜利，而是多个专业模块协同工作的必然结果。我们的系统从“蛮力并行”进化为“策略智取”，在每个环节都力求智能与高效。
zhzAI 不仅仅是一个简单的RAG应用，它是一套经过精心设计的、端到端的智能框架。
1. 离线数据处理流水线 (The Ingestion Pipeline) - 点击展开
该流水线由一个后台文件监控服务自动触发，负责将非结构化的原始文档转化为结构化的、可供检索的知识。
- 多格式智能解析 (Intelligent Parsing): 自研的调度解析器，能够处理包括
.docx,.xlsx,.pdf,.md,.html在内的多种格式。我们不仅提取纯文本，更通过深度分析，保留了文档的结构化信息（如标题层级、列表、代码块），尤其是将表格精确地转换为Markdown格式，为后续的结构化问答奠定了坚实基础。 - 高保真语义分块 (High-Fidelity Semantic Chunking): 摒弃了传统的固定大小切块方法，我们基于文档的自然语义边界进行分块，并采用动态合并与分割策略，确保每个知识块的上下文完整性。每个知识块都“知道”自己所属的章节（如
第一章 -> 1.2节），为精准过滤提供可能。 - 多维混合索引 (Multi-vector Hybrid Indexing): 我们为每一个知识块构建了双重索引：
- 稠密向量索引 (Dense Vector Index): 使用先进的文本嵌入模型，将每个知识块的“语义”转化为高维向量，存入本地的 ChromaDB。
- 稀疏关键词索引 (Sparse Keyword Index): 使用经典的 BM25 算法，为每个知识块建立高效的关键词倒排索引，保证查找特定术语时的绝对精准。
2. 在线实时查询引擎 (The Query Engine) - 点击展开
当用户发起一次查询时，我们的引擎将启动一套精密的、多阶段、多路召回的“协同作战”流程，旨在最大化召回的“广度”与“精度”。
- LLM 意图规划器 (LLM-Powered Intent Planner): 用户的自然语言查询首先会被发送给我们的本地大语言模型 (LLM) 核心。LLM 担当“总指挥”，生成结构化的JSON执行计划，实现从“大海捞针”到“靶向打击”的战略转变。
- 多路并行召回 (Multi-Path Parallel Retrieval): 系统根据LLM的执行计划，并行地向三大索引库发起检索请求：向量召回、关键词召回和图谱增强召回（架构预留，当前版本默认关闭以适配轻量级模型）。
- “小块检索，大块返回” (Small-to-Big Retrieval): 系统索引的是语义集中的“小块”，但当这些小块被命中时，会自动返回它们所属的、包含更完整上下文的“大块”，兼顾了检索的精准性和生成答案的上下文完整性。
- 多阶段融合与重排序 (Multi-Stage Fusion & Re-ranking):
- 阶段一: RRF 融合: 使用高效的倒数排序融合 (RRF) 算法，将多路召回的结果无偏见地合并成一个统一的、多样化的候选列表。
- 阶段二: 交叉编码器精排: 引入一个专门的交叉编码器 (Cross-Encoder) 模型，对候选列表进行深度语义相关性计算，输出一个高度精确的最终排序。
- 上下文感知答案生成 (Context-Aware Generation): 最终，经过层层筛选出的、最优质的知识块，将被提交给我们的本地LLM核心。我们精心设计的Prompt会指示LLM严格基于、且仅基于提供的上下文来生成答案，从根本上抑制模型幻觉。
3. 核心技术栈 - 点击展开
- 本地LLM核心: 基于 GGUF 格式的高性能推理框架，运行深度优化的开源大语言模型 (如 Qwen 1.7B)。
- AI服务框架: FastAPI
- 向量数据库与元数据过滤: ChromaDB
- 关键词检索: BM25s
- 交叉编码器与嵌入模型: 基于 SentenceTransformers
- 硬件加速: NVIDIA CUDA / cuBLAS
我的愿景是让 zhzAI 成为一个真正服务于普通打工人的AI工具。它不需要复杂的命令行操作，用户只需通过简单的图形界面就能完成安装和使用。
我的愿景是让 zhzAI 成为一个真正服务于普通打工人的AI工具。它不需要复杂的命令行操作，用户只需通过简单的图形界面就能完成安装和使用。
当前我遇到了一个巨大的挑战：
我从2025年1月中旬才开始接触电脑，不懂编程。虽然我已经通过AI完成了项目绝大部分的核心逻辑和架构设计，但在将这个复杂的系统部署到 Windows 平台时，遇到了重重困难。
-
环境依赖极其复杂
- 项目依赖
torch,llama-cpp-python,duckdb等库，在 Windows 上的编译、打包和环境隔离极具挑战。 - 我的实现细节: 为了性能，我没有完全依赖
llama-cpp-python。其中，LLM 推理部分使用的是 llama.cpp 官方的编译文件；而嵌入模型部分，则是我通过自己编译llama-cpp-python来实现的。这增加了打包的复杂度。 - 架构演进: 项目已经成功剥离了
Dagster，实现了纯 Python 的自动化数据处理流水线，并带有智能目录监控功能。
- 项目依赖
-
打包与分发是最大的瓶颈
- 我缺乏使用
PyInstaller,Nuitka或其他工具将整个 Python 项目打包成单个可执行文件 (.exe) 的经验。 - 已尝试的方案: 我已经尝试过
PyInstaller和Nuitka，但它们都无法解决llama.cpp的底层依赖问题，因此我暂时放弃了这条路，目前考虑使用嵌入式 Python 环境的方案，但这同样需要专业的工程经验。
- 我缺乏使用
-
Windows 平台迁移的“最后一公里”
- 目前的核心问题: 我不懂编程，当我尝试将项目迁移到 Windows 系统时，无法进行高效的调试和适配。
- AI 辅助的局限: AI 辅助工具在进行代码对齐和迁移时，由于项目内部各模块（如 RAG 服务、Agent 服务、LLM 接口等）的代码在逻辑和结构上具有极高的相似性导致常常混淆上下文并且出现极高的幻觉率，无法实现“像素级”的精确迁移，导致在 Windows 上的测试结果严重无法达到预期。
-
代码的工程化与重构
- 我需要有经验的开发者帮助我梳理和解耦部分核心模块，使其更易于维护和扩展。
- 需要建立一套自动化测试流程，以确保代码修改不会破坏现有功能。
我坚信这个项目在功能和架构上已经非常成熟和强大，但正被这些关键的工程化问题所困。我需要一位能够深入理解整个项目架构、而不仅仅是修改孤立代码片段的合作伙伴。如果您对解决这些挑战感兴趣，我非常期待您的帮助！
zhzAI 的目标远不止于成为一个强大的本地RAG工具。我们致力于将其打造为一个可扩展的、极小模型的端到端、离线的个人智能中枢。我们相信，通过社区的共同努力，zhzAI 的未来充满无限可能。
我们的下一步计划将围绕以下四个核心方向展开：
这是我们最高优先级的里程碑。我们将为 zhzAI 构建一个端到端、离线的长期记忆系统，使其从一个被动的知识查询工具，进化为一个能够主动服务、真正理解用户的私人助理。
- 核心能力:
- 主动记忆: 用户可以通过自然语言（如：“帮我记一下，张三下周一要还我200元”）让助理记住任何信息，包括但不限于2-20个字符的短文本、图片、视频等记忆片段。
- 智能提取与任务化: 系统将自动提取记忆中的关键实体（人物、事件、时间），并能识别出需要提醒的意图，自动创建待办事项。
- 毫秒级反馈: 记忆系统的查询和反馈将实现毫秒级响应，为未来的语音交互奠定性能基础。
- 开放性挑战: 我们正在积极探讨是为记忆系统构建独立的、高度优化的数据库架构，还是在现有RAG架构中进行统一但逻辑隔离的实现。我们欢迎社区专家就此提出宝贵建议。
为了实现真正的“智能助理”体验，我们将集成先进的本地语音技术，实现全流程的语音交互。
- 技术路径:
- 集成高效的本地语音识别 (ASR) 模型，将用户的语音指令实时、准确地转换为文本。
- 集成自然的本地语音合成 (TTS) 模型，将助理的文本回答以流畅、自然的语音播报出来。
- 设计哲学: 响应必须极致精简。例如，当用户问“谁欠我钱？”时，助理只会回答“张三、李四和王五”，而不会添加任何不必要的客套话。这种精炼的交互是提升语音助理体验的关键。
我们将持续迭代和增强现有的 RAG 核心能力，使其更智能、更强大。
- 图谱增强召回 (Graph-Enhanced Retrieval): 在当前架构预留能力的基础上，激活并优化知识图谱召回链路。当配备更强大的本地LLM时，系统将能自动构建和查询知识图谱，发掘纯文本中难以发现的深层关联信息。
- 交互式验证与澄清 (Interactive Verification & Clarification): 激活架构中预留的“交互式验证”接口，让LLM能够在面对模糊或不确定的检索结果时，主动向用户发起澄清式提问，实现更高阶的智能。
- 混合式数据源支持: 探索将结构化数据（如数据库、API）与非结构化文档无缝集成的能力，让助理能够跨越不同数据源进行联合查询。
我们将进一步利用 GBNF (GGML-based BNF) 语法约束，为本地的小模型“安装”上更可靠、更强大的“手脚”，使其能够稳定地执行各种复杂任务。
- 可靠的工具调用: 通过 GBNF 强制LLM生成格式完全正确的工具调用JSON，彻底解决小模型在Function Calling上的不稳定性问题。
- 复杂任务流编排: 设计和实现更复杂的 GBNF 语法，使小模型能够规划和输出包含多个步骤、带有逻辑判断（如IF/ELSE）的复杂任务流。
- 赋能开发者: 我们将把这套 GBNF 应用框架打磨成一个易于扩展的模块，让社区开发者可以轻松地为 zhzAI 添加新的工具和能力。
我非常期待与对本项目感兴趣的开发者交流、合作。如果您有任何想法、建议，或者愿意贡献您的力量，请通过以下方式与我联系：
- X: [@geantendormi76]
- 邮箱 (Email): [email protected]
- GitHub Issues: 对于具体的技术问题或功能建议，也欢迎您直接在 Issues 页面 发起讨论。
让我们一起构建一个更智能、更易用的本地AI助手！
- 基础配置 (人人可用):
- 操作系统: Windows 10 / 11 (64位) 或 Linux
- 内存 (RAM): 8 GB 或更高
- 处理器 (CPU): 近5年内的主流处理器即可
- 硬件加速配置 (体验起飞):
- NVIDIA 显卡 (GPU), 显存 ≥ 4 GB (例如 GTX 1660, RTX 2060/3060/4060 或更高型号)
本项目需要启动3个核心服务才能进行问答：
- 嵌入模型服务: 负责将文本转换为向量。
- 本地LLM服务: 提供大语言模型推理能力。
- RAG API 服务: 接收查询并编排整个RAG流程。
详细的安装和启动步骤请参考贡献者指南（待完善）。
我们非常欢迎任何形式的贡献！
- 报告问题 (Issues): 如果您在使用中发现任何 Bug，或者有任何功能建议，请通过 Issues 页面提交。
- 提交代码 (Pull Requests):
- 请先 Fork 本仓库。
- 在您的 Fork 中创建一个新的分支 (
git checkout -b feature/your-feature-name)。 - 进行修改并提交 (
git commit -m 'Add some feature')。 - 将您的分支推送到 GitHub (
git push origin feature/your-feature-name)。 - 创建一个 Pull Request。
本项目采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0) 许可协议。
这意味着：
- 署名 (BY): 您必须给出适当的署名。
- 非商业性使用 (NC): 您不得将本作品用于商业目的。
- 相同方式共享 (SA): 如果您对本作品进行修改、转换或二次创作，您必须以与本作品相同的许可协议分发您的贡献。
选择此许可证的核心原因，是我希望这个项目能保持其初心——服务于社区和个人用户，而不是被用于商业牟利。
感谢您的关注与支持！