# openharmony-rga

**Repository Path**: kingstk/openharmony-rga

## Basic Information

- **Project Name**: openharmony-rga
- **Description**: 这是一个基于 RAG (Retrieval-Augmented Generation) 技术的智能问答系统，专门用于查询鸿蒙文档。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 鸿蒙文档智能问答系统

## 项目简介

这是一个基于 RAG (Retrieval-Augmented Generation) 技术的智能问答系统，专门用于查询鸿蒙文档。系统能够：

- 扫描和解析多种格式的文档（PDF、Word、HTML、Markdown 等）
- 自动构建向量知识库
- 基于用户问题检索相关文档
- 结合 GLM-4.6V 模型进行图文理解
- 提供流式回答，模拟人类打字效果
- 支持多图片上传和分析

## 技术栈

- **后端**：Node.js, Express
- **向量存储**：FAISS
- **文本向量化**：Transformers.js (all-MiniLM-L6-v2)
- **LLM**：智谱 AI GLM-4.6V
- **前端**：HTML, CSS, JavaScript
- **文档处理**：pdf-parse, mammoth, turndown
- **环境管理**：@dotenvx/dotenvx

## 项目结构

```
harmony-ai/
├── models/                  # 本地模型存储目录
│   └── all-MiniLM-L6-v2/    # 文本向量化模型
├── public/                  # 前端静态文件
│   └── index.html           # 前端页面
├── buildFAISS.js            # 知识库构建脚本
├── server.js                # 后端服务器
├── package.json             # 项目配置
├── .env                     # 环境变量
├── .env.keys                # 加密密钥
└── README.md                # 项目说明
```

## 环境配置

1. **创建 .env 文件**：
   ```
   # 智谱 AI API 密钥
   ZHIPU_API_KEY=your_api_key_here
   ```

2. **加密 .env 文件**：
   ```bash
   npx dotenvx encrypt
   ```

## 本地模型设置

系统使用本地的 `all-MiniLM-L6-v2` 模型进行文本向量化，模型文件已放置在 `models/` 目录中。

## 快速开始

1. **安装依赖**：
   ```bash
   npm install
   ```

2. **构建知识库**：
   ```bash
   # 注意：处理 15000+ 文件可能需要数小时
   npm run create
   ```

3. **启动服务**：
   ```bash
   node server.js
   ```

4. **访问系统**：
   打开浏览器访问 `http://localhost:3111`

## 使用指南

### 文本问答
1. 在输入框中输入您的问题
2. 点击「发送」按钮
3. 系统会检索相关文档并生成回答

### 图文理解
1. 点击「上传图片」按钮
2. 选择本地图片文件
3. 输入与图片相关的问题
4. 系统会分析图片内容并结合文档生成回答

## 性能优化

- **并行处理**：使用多核 CPU 加速文档解析和向量化
- **进度条**：实时显示处理进度和预计完成时间
- **本地模型**：使用本地嵌入模型，避免网络延迟
- **批量处理**：优化向量化过程，提高处理速度

## 常见问题

### 1. 构建知识库时遇到网络错误

**解决方案**：系统已配置使用本地模型，确保 `models/all-MiniLM-L6-v2` 目录存在且包含完整的模型文件。

### 2. 服务启动失败

**解决方案**：检查 `.env` 文件是否正确配置了 `ZHIPU_API_KEY`。

### 3. 图片上传失败

**解决方案**：确保图片大小适中（建议小于 5MB），且格式为常见图片格式（JPG、PNG 等）。

## 相关依赖

| 依赖项 | 版本 | 用途 | 功能描述 |
|-------|------|------|---------|
| @dotenvx/dotenvx | ^1.61.0 | 环境变量管理 | 加载和管理 .env 文件中的环境变量，确保敏感信息不硬编码 |
| @langchain/core | ^1.1.38 | LangChain 核心库 | 提供 LangChain 的基础功能和抽象 |
| @langchain/community | ^1.1.27 | 社区集成 | 提供社区贡献的集成和工具，包括向量存储实现 |
| langchain | ^1.3.1 | 主库 | 构建基于 LLM 的应用，提供链式调用能力 |
| @xenova/transformers | ^2.17.2 | 模型运行库 | 在 Node.js 中运行预训练的 Transformer 模型，用于文本向量化 |
| axios | ^1.15.0 | HTTP 客户端 | 发送 API 请求 |
| cors | ^2.8.6 | 跨域中间件 | 允许前端从不同域名访问 API |
| express | ^5.2.1 | Web 框架 | 构建 API 服务 |
| express-sse | ^1.0.0 | 服务器推送 | 实现 Server-Sent Events，用于服务器向客户端推送事件 |
| faiss-node | ^0.5.1 | 向量存储 | 高效存储和检索向量嵌入，是 RAG 系统的核心组件 |
| glob | ^13.0.6 | 文件匹配 | 批量处理文件路径 |
| mammoth | ^1.12.0 | 文档处理 | 从 Word 文档中提取文本 |
| multer | ^2.1.1 | 文件上传 | 处理用户上传的文件 |
| pdf-parse | ^2.4.5 | 文档处理 | 从 PDF 文件中提取文本 |
| turndown | ^7.2.4 | 格式转换 | 将 HTML 转换为 Markdown，便于统一处理 |

## 工作原理与AI技术栈

#### 1. 主要AI技术栈

- **Transformers.js (all-MiniLM-L6-v2)**：本地文本向量化模型
  - **作用**：将文本转换为向量嵌入（embeddings），用于语义相似度计算。
  - **特点**：完全本地运行，不依赖网络；基于Transformer架构，支持中文和英文文本。

- **FAISS (Facebook AI Similarity Search)**：向量数据库
  - **作用**：高效存储和检索高维向量，支持近似最近邻搜索。
  - **特点**：开源、高性能，适合大规模向量数据。

- **LangChain**：AI应用框架
  - **作用**：提供RAG流程的工具链，包括文档分割、向量存储接口和检索逻辑。
  - **组件**：
    - `@langchain/core`：核心抽象和文档处理。
    - `@langchain/community`：社区集成，如FAISS向量存储。
    - `langchain`：主库，用于构建RAG链。

- **智谱AI GLM-4.5-flash**：大语言模型 (LLM)
  - **作用**：基于用户问题和检索上下文生成自然语言回答，支持图文理解。
  - **特点**：支持流式输出、多模态输入（文本+图片）、思维链推理。

- **其他辅助AI相关技术**：
  - **文档解析库**：pdf-parse、mammoth、turndown（用于提取PDF、Word、HTML等文档的文本内容，作为向量化输入）。
  - **环境管理**：@dotenvx/dotenvx（安全管理API密钥）。

#### 2. 技术栈之间的协同工作流程

系统的工作流程分为**离线构建阶段**和**在线问答阶段**，各技术栈紧密协作：

##### **离线构建阶段（知识库构建）**
1. **文档解析**：
   - 使用pdf-parse、mammoth等库从鸿蒙文档中提取纯文本。
   - LangChain的`RecursiveCharacterTextSplitter`将长文档分割成小块（chunkSize=1200，overlap=200），便于向量化。

2. **文本向量化**：
   - Transformers.js加载本地all-MiniLM-L6-v2模型。
   - 对每个文档块调用`embedDocuments()`生成向量嵌入。
   - 向量维度通常为384（all-MiniLM-L6-v2的标准输出）。

3. **向量存储**：
   - LangChain的`FaissStore.fromDocuments()`将向量和元数据（文档来源、文件夹）存储到FAISS索引中。
   - 生成faiss.index和docstore.json文件。

##### **在线问答阶段（RAG推理）**
1. **用户输入处理**：
   - 接收文本问题和可选图片列表。

2. **检索增强**：
   - LangChain的`FaissStore.load()`加载FAISS索引。
   - 使用本地all-MiniLM-L6-v2对用户问题进行向量化（`embedQuery()`）。
   - FAISS执行相似度搜索，返回top相关文档片段（先检索10个，再关键词过滤至5个）。

3. **上下文组装**：
   - 将检索到的文档内容拼接成prompt上下文。
   - 如果有图片，将其作为多模态输入。

4. **智能生成**：
   - 调用智谱AI GLM-4.5-flash API。
   - 发送包含上下文、问题和图片的请求。
   - GLM模型基于上下文生成回答，支持流式输出（通过SSE推送给前端）。

5. **输出展示**：
   - 前端通过Server-Sent Events (SSE)实时显示回答，模拟打字效果。

#### 3. 技术栈之间的连接关系

- **数据流连接**：
  - 文档解析 → 文本向量化 → FAISS存储 → 检索 → LLM生成。
  - LangChain作为“胶水层”，统一管理向量化和检索流程，确保兼容性。

- **模块化设计**：
  - Transformers.js和FAISS专注于底层AI计算（向量化+检索），LangChain提供高层抽象。
  - GLM作为外部LLM服务，通过API集成，不依赖本地计算资源。

- **性能优化**：
  - 本地模型（Transformers.js）避免网络延迟，提升检索速度。
  - FAISS的高效索引支持实时查询。
  - 并行处理（多核CPU）加速构建阶段。

- **多模态支持**：
  - GLM-4.5-flash连接文本检索和图片理解，实现“文档+图片”联合问答。

## 优化方案

#### 1. **改进检索机制（最直接有效）**
   - **混合检索 (Hybrid Search)**：
     - 当前仅用向量相似度检索，添加关键词匹配（如BM25算法）。
     - **实施**：集成`@langchain/community`的`BM25Retriever`，结合FAISS向量检索。检索时，先用BM25过滤候选，再用向量重排序。
     - **优势**：提升精确匹配，减少无关文档干扰。
     - **工具**：LangChain支持混合检索，无需更换FAISS。

   - **检索结果重排序 (Re-ranking)**：
     - 对初始检索结果用更强的模型（如Cross-Encoder）重新评分。
     - **实施**：使用Hugging Face的`sentence-transformers`模型（如`ms-marco-MiniLM-L-6-v2`）对查询-文档对评分。
     - **优势**：显著提升top结果的相关性。

   - **查询扩展 (Query Expansion)**：
     - 用LLM生成查询变体（如同义词、相关问题）。
     - **实施**：在`ragRetrieve`函数中，先调用GLM生成扩展查询，再检索。
     - **优势**：处理模糊或复杂问题。

#### 2. **增强RAG架构**
   - **多文档融合 (Multi-Document Fusion)**：
     - 当前返回top 5文档，改为用LLM总结或融合多个片段。
     - **实施**：在prompt中添加“请综合以下文档回答”，让GLM自行处理冲突。
     - **优势**：减少片段级噪声，提升整体一致性。

   - **知识图谱集成 (Knowledge Graph)**：
     - 构建鸿蒙文档的实体关系图（如组件依赖、API调用）。
     - **实施**：用Neo4j或RDF存储图谱，检索时结合向量和图查询。
     - **优势**：处理结构化知识，如“组件A依赖B”。

   - **多轮对话记忆 (Conversational RAG)**：
     - 记住历史对话，避免重复检索。
     - **实施**：用LangChain的`ConversationBufferMemory`存储上下文。
     - **优势**：提升连续问答的准确性。

#### 3. **模型层面优化**
   - **切换更强LLM**：
     - 当前用GLM-4.5-flash，考虑GPT-4o或Claude-3（需API密钥）。
     - **实施**：修改server.js中的API调用，添加模型选择。
     - **优势**：更强的推理能力，减少幻觉。

   - **模型微调 (Fine-Tuning)**：
     - 在鸿蒙文档上微调GLM模型。
     - **实施**：用智谱AI的微调API或本地LoRA训练。
     - **优势**：针对性强，准确性提升显著（但需数据准备）。

   - **事实检查机制 (Fact-Checking)**：
     - 生成回答后，用另一个模型验证事实。
     - **实施**：添加后处理步骤，调用GLM检查“基于文档是否正确”。
     - **优势**：减少错误输出。

#### 4. **数据和预处理优化**
   - **文档质量提升**：
     - 过滤低质量文档（如重复或无关内容）。
     - **实施**：在buildFAISS.js中添加预过滤逻辑。

   - **更智能切片 (Chunking)**：
     - 当前用固定大小，改为语义切片（如按段落或标题）。
     - **实施**：用LangChain的`SemanticChunker`或自定义逻辑。
     - **优势**：保留上下文完整性。

   - **增量更新知识库**：
     - 支持新文档动态添加，而非全量重建。
     - **实施**：修改buildFAISS.js为增量模式。

#### 5. **其他架构方案**
   - **Agent架构 (Autonomous Agents)**：
     - 让模型自主决定检索、推理和工具调用。
     - **实施**：用LangChain Agents集成工具（如搜索、计算）。
     - **优势**：更灵活，适合复杂问题。

   - **向量数据库升级**：
     - 从FAISS换到Pinecone或Chroma，支持元数据过滤和混合检索。
     - **实施**：修改server.js中的存储接口。
     - **优势**：云端托管，更易扩展。

   - **外部搜索集成**：
     - 若文档不足，fallback到网络搜索。
     - **实施**：添加SerpAPI或Bing Search API调用。
     - **优势**：补充最新信息。


## 鸿蒙文档获取

- [OpenHarmony 官方文档](https://gitcode.com/openharmony/docs/tree/master?tab=md)
- [MiniLM-L6 本地文本向量化模型](https://huggingface.co/Xenova/all-MiniLM-L6-v2/tree/main)

## 许可证

MIT License