# ueragguid

**Repository Path**: alienity/ueragguid

## Basic Information

- **Project Name**: ueragguid
- **Description**: UE 引擎源码 RAG 系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UE 引擎源码 RAG 系统

## 项目概述
本项目旨在为 Unreal Engine（UE）引擎源码构建一个检索增强生成（RAG）系统，帮助开发者快速查询和理解 UE 庞大的代码库。通过向量数据库、知识图谱和流程提取技术，实现对 UE 源码的语义搜索，特别是能够直接回答"UE 引擎的渲染管线流程"这类高层问题。

## 什么是 RAG

### RAG 概念
**检索增强生成（Retrieval-Augmented Generation，RAG）** 是一种结合检索和生成的 AI 技术架构。它的核心思想是：
1. 当用户提出问题时，系统首先从知识库中**检索**相关文档或片段
2. 然后将检索结果与问题一起发送给大语言模型
3. 模型基于检索到的上下文**生成**准确的回答

### 为什么需要 RAG

| 问题 | 纯 LLM 方案 | RAG 方案 |
|------|-----------|---------|
| **知识时效性** | 受限于训练数据截止日期 | 可实时更新知识库 |
| **领域专业性** | 通用知识，缺乏深度 | 可索引专业领域文档 |
| **幻觉问题** | 可能编造不存在的信息 | 基于真实文档回答 |
| **上下文长度** | 受模型上下文窗口限制 | 可检索海量文档 |
| **可追溯性** | 难以验证信息来源 | 可定位原始文档 |

### RAG 工作流程

#### 索引阶段
```
UE 源码 → 分块 → CodeBERT 嵌入 → 向量数据库
              ↓
         流程提取 → 知识图谱
```

#### 查询阶段
```
用户查询 → 意图识别 → 路由选择
                        ↓
           ┌────────────┴────────────┐
           ↓                         ↓
    流程查询 (知识图谱)        代码搜索 (向量检索)
           ↓                         ↓
           └────────────┬────────────┘
                        ↓
                  结构化回答
```

### 本项目的 RAG 实现特点

1. **代码级向量化**: 使用 CodeBERT 将 C++ 代码片段转换为向量，支持语义搜索
2. **结构化元数据**: 每个代码块携带模块名、类名、继承关系等元数据，支持精确过滤
3. **知识图谱增强**: 构建函数调用关系图，支持流程类查询（如渲染管线、Tick 流程）
4. **双层检索**:
   - 向量检索：查找语义相似的代码片段
   - 图检索：查找流程中的上下游关系

## 系统架构

### 整体架构图

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           用户接口层                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                  │
│  │  CLI 查询     │  │  VS Code 插件 │  │  Web UI     │                  │
│  └──────────────┘  └──────────────┘  └──────────────┘                  │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────┐
│                           查询处理层                                     │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐            │
│  │ 查询意图识别    │→ │ 向量检索        │→ │ 结果重排序      │            │
│  │ (query_*)      │  │ (chroma_client)│  │ (flow_search)  │            │
│  └────────────────┘  └────────────────┘  └────────────────┘            │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────┐
│                           数据存储层                                     │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐            │
│  │ ChromaDB       │  │ 知识图谱 JSON   │  │ 配置文件        │            │
│  │ (向量索引)      │  │ (流程关系)      │  │ (模式定义)      │            │
│  └────────────────┘  └────────────────┘  └────────────────┘            │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↑
┌─────────────────────────────────────────────────────────────────────────┐
│                           索引构建层                                     │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐            │
│  │ 文件发现        │→ │ C++ 解析器      │→ │ 代码分块        │            │
│  │ (file_*)       │  │ (parser/)      │  │ (chunking)     │            │
│  └────────────────┘  └────────────────┘  └────────────────┘            │
│         ↓                ↓                ↓                             │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐            │
│  │ 流程提取        │→ │ 知识图谱构建    │→ │ CodeBERT 嵌入   │            │
│  │ (flow_*)       │  │ (knowledge_*)  │  │ (embedding/)   │            │
│  └────────────────┘  └────────────────┘  └────────────────┘            │
└─────────────────────────────────────────────────────────────────────────┘
```

### 核心模块职责

| 层级 | 模块 | 职责 |
|------|------|------|
| **查询层** | `query_understanding` | 识别查询意图（流程查询 vs 代码搜索） |
| | `flow_search` | 基于知识图谱的流程检索 |
| **存储层** | `chroma_client` | 向量存储和相似度搜索 |
| **索引层** | `file_discovery` | UE 源码文件发现与过滤 |
| | `cpp_parser` + `ue_macro` | C++ 代码解析，UE 宏展开 |
| | `chunking` | 代码分块（类级/函数级） |
| | `flow_extractor` | 渲染管线、Tick 流程提取 |
| | `knowledge_graph` | 构建函数调用关系图 |
| | `codebert_embedder` | 代码向量化 |

### 数据流

#### 索引阶段（离线）
```
UE 源码目录
    ↓
┌─────────────────────────────────────────────────┐
│ 1. 文件发现：扫描 Engine/Source/ 下的.h/.cpp    │
│ 2. 代码解析：提取 UCLASS/UFUNCTION等宏定义      │
│ 3. 代码分块：按类/函数切分，添加元数据          │
│ 4. 向量化：CodeBERT生成嵌入 → 存入 ChromaDB     │
│ 5. 流程提取：识别渲染管线、Tick流程关键函数     │
│ 6. 图构建：建立函数调用关系 → 保存JSON          │
└─────────────────────────────────────────────────┘
```

#### 查询阶段（在线）
```
用户查询："UE 渲染管线流程"
    ↓
┌─────────────────────────────────────────────────┐
│ 1. 意图识别：检测关键词 → 分类为"render_pipeline"│
│ 2. 路由选择：流程查询 → 知识图谱检索            │
│ 3. 结果获取：按执行顺序返回流程步骤             │
│ 4. 格式化：输出结构化Markdown                   │
└─────────────────────────────────────────────────┘
    ↓
## UE 引擎渲染管线流程
1. FRendererModule::RenderViewFamily ...
```

### 查询类型路由

| 查询类型 | 关键词 | 数据源 | 返回格式 |
|---------|--------|--------|---------|
| 渲染管线 | "渲染管线", "render pipeline" | 知识图谱 | 流程步骤列表 |
| Tick 流程 | "tick 流程", "游戏循环" | 知识图谱 | 流程步骤列表 |
| 代码搜索 | 其他 | ChromaDB 向量检索 | Top-K 代码片段 |

## 目录结构
```
ueragguid/
├── src/
│   ├── core/                  # 核心处理模块
│   │   ├── file_discovery.py  # UE 源码发现
│   │   ├── parser/            # 解析器模块
│   │   ├── flow_extractor.py  # 流程提取器
│   │   ├── knowledge_graph.py # 知识图谱构建
│   │   └── chunking.py        # 代码分块
│   ├── vector_db/            # ChromaDB 集成
│   ├── embedding/            # CodeBERT 嵌入
│   └── search/               # 搜索引擎
│       ├── query_understanding.py  # 查询意图识别
│       └── flow_search.py          # 流程查询
├── config/
│   ├── flow_patterns.json     # 流程模式配置
│   └── ue_paths.json          # UE 路径配置
├── scripts/
│   ├── index_ue_source.py     # 主索引脚本
│   └── query_interface.py     # 查询接口
└── requirements.txt           # 依赖包
```

## 安装和使用

### 环境准备
```bash
# 克隆项目
git clone https://gitee.com/alienity/ueragguid.git
cd ueragguid

# 创建虚拟环境
python -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

### 依赖说明
- **Python 3.8+**: 基础运行环境
- **ChromaDB**: 向量数据库（HNSW 索引）
- **Transformers**: HuggingFace 模型加载（CodeBERT）
- **PyTorch**: 深度学习框架（可选，用于完整嵌入）
- **Tree-sitter**: C++ AST 解析（可选，计划中）

### 索引 UE 源码
```bash
# 索引 UE 源码并构建知识图谱
python scripts/index_ue_source.py --engine-path /path/to/UnrealEngine_5.3
```

### 智能查询示例
```bash
# 直接获取渲染管线流程
python scripts/query_interface.py --query "UE 引擎的渲染管线流程"

# 获取 Tick 流程
python scripts/query_interface.py --query "UE 引擎的 tick 流程"

# 普通代码搜索
python scripts/query_interface.py --query "如何实现 Actor 的移动"
```

### 技术特色

#### 流程提取能力
- **渲染管线**: 从 RenderViewFamily 到帧提交的完整流程
- **Tick 流程**: 从 UWorld::Tick 到 AActor::Tick 的游戏循环
- **自动识别**: 基于关键词自动分类查询意图

#### 知识图谱
- **实体关系**: 函数、类、模块之间的调用和依赖关系
- **流程排序**: 按执行顺序组织流程步骤
- **结构化输出**: 清晰的步骤列表和详细说明

#### 元数据过滤
ChromaDB 支持按元数据条件过滤检索结果：
- 按模块名过滤：`{"module": "Renderer"}`
- 按类名过滤：`{"class_name": "UWorld"}`
- 按分块类型过滤：`{"chunk_type": "function"}`

---

## 实现边界

### 当前实现（已完成）

| 功能 | 实现状态 | 说明 |
|------|---------|------|
| 文件发现 | ✅ 完成 | 支持.h/.cpp文件扫描，排除Tests/Intermediate |
| C++ 解析 | ✅ 简化版 | 正则表达式提取 UE 宏，非 AST 解析 |
| 代码分块 | ✅ 完成 | 类级分块，支持大内容分块接口 |
| 流程提取 | ✅ 完成 | 渲染管线、Tick 流程（预定义模式） |
| 知识图谱 | ✅ 完成 | JSON 存储，支持流程关系查询 |
| 向量检索 | ⚠️ 部分完成 | ChromaDB 集成完成，CodeBERT 需资源配置 |
| 查询接口 | ✅ 完成 | CLI 查询，意图识别，流程查询 |

### 计划中功能 - 全部完成 ✅

| 功能 | 优先级 | 状态 | 说明 |
|------|--------|------|------|
| Tree-sitter AST 解析 | 高 | ✅ 完成 | 集成 tree-sitter-cpp |
| 完整 CodeBERT 嵌入 | 高 | ✅ 完成 | Qwen2.5-Coder 1.5B |
| 更多流程类型 | 中 | ✅ 完成 | 加载/网络/物理流程 |
| LLM 集成生成 | 中 | ✅ 完成 | Qwen/Ollama/Mock |
| VS Code 插件 | 低 | ✅ 完成 | vscode-extension/ |
| Web UI | 低 | ✅ 完成 | webui/ (Flask) |

## 当前状态

详细实现进度见 [实现边界](#实现边界) 章节。

## 使用示例

当查询"UE 引擎的渲染管线流程"时，系统会返回：

```
## UE 引擎渲染管线流程

1. **FRendererModule::RenderViewFamily**
   - 文件：`Engine/Source/Runtime/Renderer/Private/RendererModule.cpp`
   - 描述：渲染视图家族的主入口

2. **FSceneRenderer::InitViews**
   - 文件：`Engine/Source/Runtime/Renderer/Private/SceneRendering.cpp`
   - 描述：初始化视图相关数据，包括可见性计算

...（更多步骤）

### 详细说明
渲染管线主要分为以下几个阶段：
1. **入口点**: 渲染视图家族的主入口，负责初始化渲染器
2. **场景渲染**: 处理几何体、光照、阴影等核心渲染操作
3. **后处理**: 应用 Bloom、DOF、色调映射等视觉效果
4. **帧提交**: 将最终渲染结果提交到显示设备
```

## 许可证
MIT License