项目概述
本文介绍了HarmonySmartCoding项目中RAG（Retrieval-Augmented Generation）功能的完整实现，该功能为开发者提供了智能的API文档检索和问答服务。通过结合向量检索和语义理解，用户可以通过自然语言查询快速找到相关的HarmonyOS API文档和代码示例。
技术架构
整体架构设计
前端 (Vue.js) ←→ 后端 (Flask) ←→ RAG引擎 (BGE模型)
↓ ↓ ↓
用户界面 API接口 向量数据库
核心组件
- 前端界面 (
PureRAG.vue): 提供用户交互界面 - 后端API (
app.py): 处理HTTP请求和响应 - RAG引擎 (
rag_engine.py): 核心检索逻辑 - 样式系统 (
pureRAG.scss): 界面样式定义
后端实现
RAG引擎核心 (rag_engine.py)
class RAGEngine:
def __init__(self, bge_model_path, docs_path, doc_ids_path, embeddings_path):
# 加载本地 BGE 模型
self.model = SentenceTransformer(bge_model_path)
# 加载RAG数据库
with open(docs_path, 'r', encoding='utf-8') as f:
self.docs = json.load(f)
with open(doc_ids_path, 'r', encoding='utf-8') as f:
self.doc_ids = json.load(f)
with open(embeddings_path, 'rb') as f:
self.embeddings = pickle.load(f)
核心特性：
- 使用BGE（BAAI General Embedding）模型进行文本向量化
- 支持本地模型部署，确保数据安全性
- 预计算文档向量，提高检索效率
检索算法实现
def search(self, query, top_k=3):
"""根据查询检索相关文档"""
query_emb = self.get_query_embedding(query)
# 计算余弦相似度
sims = np.dot(self.embeddings, query_emb) / \
(np.linalg.norm(self.embeddings, axis=1) * np.linalg.norm(query_emb) + 1e-8)
top_indices = sims.argsort()[-top_k:][::-1]
# 构建结果列表
results = []
for idx in top_indices:
doc = self.docs[idx]
doc_id = self.doc_ids[idx]
score = float(sims[idx])
results.append({
"doc_id": doc_id,
"title": doc.get("title", ""),
"overview": doc.get("overview", ""),
"sections": doc.get("sections", []),
"score": score
})
return results
算法优势：
- 使用余弦相似度计算文档相关性
- 支持可配置的返回结果数量
- 包含相似度评分，便于结果排序
Flask API接口 (app.py)
@app.route('/api/rag_query', methods=['POST'])
def rag_query():
data = request.get_json()
query = data.get('query', '')
top_k = data.get('top_k', 3)
if not query:
return jsonify({'error': 'No query provided'}), 400
try:
# 执行RAG搜索
results = rag_engine.search(query, top_k=top_k)
# 格式化响应
resp = rag_engine.format_api_response(query, results)
return jsonify(resp)
except Exception as e:
return jsonify({'error': f'RAG 查询失败: {str(e)}'}), 500
接口特性：
- RESTful API设计
- 完善的错误处理机制
- 支持CORS跨域请求
- 详细的调试日志
前端实现
Vue组件架构 (PureRAG.vue)
<template>
<div class="pure-rag-page" :class="{ 'dark-mode': isDarkMode }">
<!-- 搜索区域 -->
<div class="search-area">
<div class="search-box">
<input
v-model="searchQuery"
type="text"
placeholder="输入自然语言问题或API名称..."
@keyup.enter="performSearch"
class="search-input"
/>
<!-- 自动补全下拉框 -->
<div v-if="showAutocomplete" class="autocomplete-dropdown">
<!-- 智能建议项 -->
</div>
</div>
</div>
<!-- 内容展示区 -->
<div class="page-content">
<!-- 历史记录侧边栏 -->
<div class="history-sidebar">
<!-- 搜索历史 -->
</div>
<!-- 搜索结果区 -->
<div class="result-content">
<!-- 智能回答 -->
<div class="answer-section">
<h3>智能回答</h3>
<div class="answer-content" v-html="formatAnswer(apiResult.answer)"></div>
</div>
<!-- 相关文档列表 -->
<div class="relevant-docs-section">
<h3>相关文档 ({{ apiResult.total_docs }})</h3>
<div class="docs-list">
<!-- 文档项展示 -->
</div>
</div>
</div>
</div>
</div>
</template>
核心功能实现
1. 智能搜索
const performSearch = async () => {
if (!searchQuery.value.trim()) return;
loading.value = true;
try {
const response = await RAGService.query({
query: searchQuery.value,
top_k: 5
});
apiResult.value = response.data;
// 保存搜索历史
saveToHistory(searchQuery.value);
} catch (error) {
console.error('搜索失败:', error);
} finally {
loading.value = false;
}
};
2. 自动补全功能
const handleInput = _.debounce(() => {
const query = searchQuery.value.trim();
if (!query) {
showAutocomplete.value = false;
return;
}
// 智能问答模式
if (/如何|怎么|怎样/.test(query)) {
const matchedKeywords = Object.keys(questionToApiMap)
.filter(keyword => query.includes(keyword));
if (matchedKeywords.length > 0) {
autocompleteItems.value = matchedKeywords
.flatMap(keyword =>
questionToApiMap[keyword].map(api => ({
text: `智能推荐：${api}`,
type: 'smart',
fullText: api,
description: getAPIDescription(api)
}))
)
.slice(0, 5);
showAutocomplete.value = true;
}
}
}, 300);
3. 搜索历史管理
const saveToHistory = (query) => {
const historyItem = {
id: Date.now(),
query: query,
timestamp: new Date(),
language: codeLanguage.value
};
history.value.unshift(historyItem);
// 限制历史记录数量
if (history.value.length > 50) {
history.value = history.value.slice(0, 50);
}
// 持久化存储
localStorage.setItem('rag_search_history', JSON.stringify(history.value));
};
样式系统 (pureRAG.scss)
响应式布局设计
.pure-rag-page {
display: flex;
flex-direction: column;
height: 100%;
background-color: var(--bg-color);
.page-content {
display: flex;
flex: 1;
overflow: hidden;
.history-sidebar {
width: 300px;
min-width: 300px;
border-right: 1px solid var(--border-color);
}
.result-content {
flex: 1;
overflow-y: auto;
padding: 16px;
}
}
}
暗黑模式支持
:root {
--primary-color: #4361ee;
--text-color: #2d3748;
--bg-color: #ffffff;
--border-color: #e2e8f0;
}
.dark-mode {
--primary-color: #4dabf7;
--text-color: #e2e8f0;
--bg-color: #1a202c;
--border-color: #2d3748;
}
功能特性
1. 智能检索
- 语义理解：基于BGE模型的语义向量检索
- 多模态查询：支持自然语言问题和API名称查询
- 相似度评分：提供检索结果的相关性评分
2. 用户体验
- 实时搜索：输入即搜索，响应迅速
- 自动补全：智能推荐相关API和问题
- 搜索历史：保存和管理搜索记录
- 暗黑模式：支持明暗主题切换
3. 内容展示
- 结构化展示：清晰的文档结构和层次
- 代码高亮：语法高亮的代码示例
- 表格支持：完整的表格内容展示
- 展开收起：可折叠的详细内容
4. 交互功能
- 一键复制：快速复制代码和内容
- 反馈机制：用户反馈和建议收集
- 快捷操作：键盘快捷键支持
技术亮点
1. 本地化部署
- 使用本地BGE模型，确保数据安全
- 离线运行能力，不依赖外部API
- 可定制化的模型配置
2. 高性能检索
- 预计算文档向量，检索速度快
- 向量化存储，内存使用效率高
- 批量处理能力，支持大规模文档库
3. 前后端分离
- RESTful API设计，接口清晰
- 前端组件化开发，易于维护
- 响应式设计，适配多种设备
4. 可扩展架构
- 模块化设计，易于功能扩展
- 配置化参数，灵活调整
- 插件化接口，支持自定义功能
部署和使用
后端启动
# 安装依赖
pip install -r requirements.txt
# 启动Flask服务
python app.py
前端启动
# 安装依赖
npm install
# 启动开发服务器
npm run serve
配置说明
# config.py
BGE_MODEL_PATH = "./models/bge-small-zh-v1.5"
DOCS_PATH = "./data/rag_db/docs.json"
DOC_IDS_PATH = "./data/rag_db/doc_ids.json"
EMBEDDINGS_PATH = "./data/rag_db/embeddings.pkl"
总结
本RAG功能实现展示了现代AI应用开发的完整流程，从后端的向量检索引擎到前端的用户交互界面，每个环节都经过精心设计和优化。通过结合语义理解和传统检索技术，为开发者提供了高效、准确的API文档查询服务。
该实现不仅在技术上具有先进性，在用户体验上也做了大量优化，包括智能补全、搜索历史、暗黑模式等功能，做到了技术与体验的结合。
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
