delorex/test-repo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): integrate version2 curriculum and stage-3 updates

Browse Source 
概要
- 将 version2 分支的课程结构重构、第三阶段章节新增、示例资源迁移、高级 RAG 文档与 Vercel 部署配置等整合为 main 上的一次汇总提交

内容导航与 README 调整
- 更新 README 的总体介绍文案，引入“第零阶段 + 第一到第三阶段”的完整学习路径描述
- 将原先的“三阶段实战路径”说明替换为新版分阶段描述，突出从小游戏到跨平台复杂应用的学习节奏
- 删除已过时的“第二次更新将在分支 version2 合并到主分支”的提示，改为直接以 main 为主线
- 统一 README 顶部标题和排版风格，保证中英文导航、徽章展示等视觉结构一致

课程结构与章节导航更新
- 调整 docs 目录下的学习阶段导航结构，使 README 中的导航表与各 stage 实际目录对齐
- 补全并创建 stage-3 相关章节入口文件，用于承载高级阶段的课程内容
- 新增或更新以下章节入口：
  - 高级核心技能：
    - docs/stage-3/core-skills/3.1-mcp-claudecode-skills/index.md
    - docs/stage-3/core-skills/3.2-long-running-tasks/index.md
  - 多平台开发：
    - docs/stage-3/cross-platform/3.3-wechat-miniprogram/index.md
    - docs/stage-3/cross-platform/3.4-wechat-miniprogram-backend/index.md
    - docs/stage-3/cross-platform/3.5-android-app/index.md
    - docs/stage-3/cross-platform/3.6-ios-app/index.md
  - 个人品牌：
    - docs/stage-3/personal-brand/3.7-personal-website-blog/index.md
- 保持 stage-0、stage-1、stage-2 既有章节结构不变的前提下，对导航表格进行排版和链接校正，使整体课程地图清晰、可点击

示例与图片资源重组
- 将原先位于 docs/examples/example1/images/ 下的微信小程序示例图片，整体迁移到 stage-3 的正式课程路径中：
  - 目标路径：docs/stage-3/3.3-how-to-build-a-wechat-miniprogram/example1/images/
- 通过 rename 方式保留 git 历史关系，避免图片资源被视为完全新增，从而方便后续追踪
- 为微信小程序示例新增 index 页面：
  - docs/stage-3/3.3-how-to-build-a-wechat-miniprogram/example1/index.md
- 使该示例在“高级三：多平台开发：如何构建微信小程序”章节中有清晰的入口，对应实际实战内容

高级 RAG 与 AI 进阶文档
- 新增一篇系统介绍 RAG 的高级文档：
  - docs/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md
- 覆盖内容包括：RAG 的基本概念、典型架构、工作流程以及未来演进方向，为第三阶段的复杂应用提供知识检索基础
- 配套引入多张插图，帮助读者从架构图和流程视角理解 RAG：
  - docs/stage-3/ai-advanced/3.a1-rag-introduction/images/image1.png ~ image15.png

部署与工程配置
- 新增 vercel.json 配置文件，为项目在 Vercel 上的部署提供基础配置
  - 明确文档构建产物的输出路径和静态站点托管方式
  - 为之后的一键部署和自动化预览打下基础

依赖与锁文件更新
- 调整 package.json 中与新版文档结构和部署相关的配置，保持脚本和依赖与当前课程形态同步
- 更新 package-lock.json，以反映最新的依赖树和版本锁定状态
- 保证在执行 npm install / npm run build 时，依赖环境与 version2 中的实际使用情况一致

兼容性与行为说明
- 该提交通过 npm run build 验证，确保在整合 version2 内容后，VitePress 构建过程正常完成
- main 分支上的历史被压缩为一条有语义的“第二次大更新”提交，详细的开发过程仍保留在 version2 分支，用于后续需要时回溯
This commit is contained in:
sanbuphy
2026-01-12 12:21:35 +08:00
parent 307a37cdb9
commit a4b583b13f
632 changed files with 18082 additions and 8092 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/extra/README.md
+10
View File
@@ -0,0 +1,10 @@
# Extra 扩展知识
这里包含了额外的扩展知识文档：
- [Extra 1: Git and GitHub](extra1/extra1-what-is-git-and-what-is-github.md)
- [Extra 2: What is API](extra2/extra2-what-is-api.md)
- [Extra 3: AI Capability Starter Handbook](extra3/extra3-ai-capability-starter-handbook.md)
- [Extra 5: What is RAG](extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md)
- [Extra 6: Zeabur Deployment](extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md)
- [Extra 7: CLI AI Coding Tools](extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md)
docs/extra/extra1/extra1-what-is-git-and-what-is-github.md
+32 -32
View File
@@ -44,13 +44,13 @@ Git 是由 Linux 内核开发者 Linus Torvalds 于 2005 年创建的分布式
1. 前往 [Git 官方下载页面](https://git-scm.com/download/win) 并下载适合你系统的安装程序：[安装包](https://github.com/git-for-windows/git/releases/download/v2.51.0.windows.1/Git-2.51.0-64-bit.exe)。默认情况下，推荐使用 x64 安装程序。
2. 双击安装程序并按照安装向导说明进行操作：
![](images/image5.png)
![](images/image5.png)
1. 建议保持默认选项。如果你需要自定义，请注意以下几点：（在大多数情况下，你可以一直点击“Next”）
* 选择 Git 使用的默认编辑器：选择你喜欢的编辑器（如 VS Code）。你可以默认选择第一个选项，即 Vim（一个文本编辑器），或选择“Visual Studio Code as Git's default editor”选项（需要预先安装 VS Code）。你可以保持默认选择并点击“Next”继续。
![](images/image6.png)
* 选择如何使用 Git：这三个选项控制 Git 在系统中的可访问性。建议选择选项 2（“from command line and 3rd-party software”）——它将基本的 Git 工具添加到 PATH 中，让你可以在 Git Bash、命令提示符、PowerShell 和 IDE 中使用 Git，而不会使系统混乱。
![](images/image7.png)
- 选择 Git 使用的默认编辑器：选择你喜欢的编辑器（如 VS Code）。你可以默认选择第一个选项，即 Vim（一个文本编辑器），或选择“Visual Studio Code as Git's default editor”选项（需要预先安装 VS Code）。你可以保持默认选择并点击“Next”继续。
![](images/image6.png)
- 选择如何使用 Git：这三个选项控制 Git 在系统中的可访问性。建议选择选项 2（“from command line and 3rd-party software”）——它将基本的 Git 工具添加到 PATH 中，让你可以在 Git Bash、命令提示符、PowerShell 和 IDE 中使用 Git，而不会使系统混乱。
![](images/image7.png)
3. 安装后，在桌面上右键单击。如果在菜单中看到“Git Bash Here”，则安装成功。
![](images/image8.png)
@@ -70,20 +70,20 @@ Git 是由 Linux 内核开发者 Linus Torvalds 于 2005 年创建的分布式
大多数 Linux 发行版可以通过其包管理器安装 Git：
* Ubuntu/Debian:
- Ubuntu/Debian:
```Bash
sudo apt update
sudo apt install git
```
* CentOS/RHEL:
- CentOS/RHEL:
```Bash
sudo yum install git
```
* 验证安装：在终端中输入 git --version。如果显示版本号，则安装成功。
- 验证安装：在终端中输入 git --version。如果显示版本号，则安装成功。
## Git 初始化
@@ -118,7 +118,7 @@ GitHub 不仅是世界上最大的代码托管平台，也是全球最活跃、
## 注册 GitHub 账号
1. 访问 [GitHub 官网](https://github.com/) 并点击右上角的“Sign up”。
![](images/image11.png)
![](images/image11.png)
2. 输入你的电子邮件地址（建议使用常用邮箱，因为验证和通知将发送到那里），设置密码（必须包含字母、数字和特殊字符）。
3. 完成人工验证，按照提示验证邮箱，你的账号就创建好了。
@@ -166,8 +166,8 @@ GitHub 不仅是世界上最大的代码托管平台，也是全球最活跃、
GitHub 支持两种主要的仓库操作协议：HTTPS 协议和 SSH 协议：
* HTTPS 协议：每次操作（如 push）都需要输入 GitHub 账号密码（或个人访问令牌 PAT）。验证过程繁琐，且存在密码泄露风险。
* SSH 协议：身份验证通过“密钥对”完成，因此不需要重复输入密码，且加密传输更加安全。
- HTTPS 协议：每次操作（如 push）都需要输入 GitHub 账号密码（或个人访问令牌 PAT）。验证过程繁琐，且存在密码泄露风险。
- SSH 协议：身份验证通过“密钥对”完成，因此不需要重复输入密码，且加密传输更加安全。
“SSH 协议绑定”是启用 GitHub SSH 认证的前提步骤——只有将本地 SSH 公钥“绑定”到 GitHub 账号后，GitHub 才能识别你的设备并允许对仓库进行 SSH 操作。
@@ -180,9 +180,9 @@ SSH 认证依赖于密钥对（公钥 + 私钥），它们是匹配的加密文
当你通过 SSH 操作 GitHub 仓库时（例如 git push git@github.com:xxx/xxx.git）：
* 你的本地设备使用私钥加密“操作请求”并发送给 GitHub；
* 收到请求后，GitHub 尝试使用你之前绑定的公钥进行解密；
* 如果解密成功，你的设备被确认为已授权，操作被允许；否则，访问被拒绝。
- 你的本地设备使用私钥加密“操作请求”并发送给 GitHub；
- 收到请求后，GitHub 尝试使用你之前绑定的公钥进行解密；
- 如果解密成功，你的设备被确认为已授权，操作被允许；否则，访问被拒绝。
### “绑定”的具体步骤（核心流程）
@@ -192,23 +192,23 @@ SSH 认证依赖于密钥对（公钥 + 私钥），它们是匹配的加密文
1. 使用 Trae 获取公钥（推荐）
提示词：`Help me create the SSH key needed for GitHub login. My email is your_email@gmail.com , Please return the public key for me to copy`
![](images/image18.png)
![](images/image18.png)
输入提示词后，你还需要在左侧终端按 Enter 键，否则命令会一直等待而不执行。由于 Trae 无法帮你执行任何条件判断，我们只需要一直按 Enter 即可。
输入提示词后，你还需要在左侧终端按 Enter 键，否则命令会一直等待而不执行。由于 Trae 无法帮你执行任何条件判断，我们只需要一直按 Enter 即可。
最后，你会看到右侧的 Trae 返回了它读取的公钥。你只需复制它并准备在下一步中粘贴。
最后，你会看到右侧的 Trae 返回了它读取的公钥。你只需复制它并准备在下一步中粘贴。
![](images/image19.png)
2. 手动获取公钥
打开你的本地终端（在 Windows 上使用 Git Bash 或 PowerShell；在 macOS/Linux 上使用终端），输入以下命令（将 your_email@example.com 替换为你注册 GitHub 账号时使用的邮箱）：
![](images/image19.png) 2. 手动获取公钥
打开你的本地终端（在 Windows 上使用 Git Bash 或 PowerShell；在 macOS/Linux 上使用终端），输入以下命令（将 your_email@example.com 替换为你注册 GitHub 账号时使用的邮箱）：
```Bash
ssh-keygen -t ed25519 -C "your_email@example.com"
```
```Bash
ssh-keygen -t ed25519 -C "your_email@example.com"
```
1. 按 Enter 接受默认值（默认文件路径，无密码，或根据需要设置密码）。这将在 ~/.ssh/ 目录中生成两个文件：
- id_ed25519：私钥（本地保存，**绝不分享**）；
- id_ed25519.pub：公钥（需要上传到 GitHub）。
1. 按 Enter 接受默认值（默认文件路径，无密码，或根据需要设置密码）。这将在 ~/.ssh/ 目录中生成两个文件：
* id_ed25519：私钥（本地保存，**绝不分享**）；
* id_ed25519.pub：公钥（需要上传到 GitHub）。
2. 将公钥“绑定”到你的 GitHub 账号
这是核心绑定步骤——将本地公钥添加到 GitHub 账号的“SSH keys list”中：
@@ -219,7 +219,7 @@ SSH 认证依赖于密钥对（公钥 + 私钥），它们是匹配的加密文
3. macOS/Linux：在终端运行 cat ~/.ssh/id_ed25519.pub 并复制所有输出（从开头的 SSH-ed25519 到结尾的邮箱）。
2. 登录 GitHub 并进入“SSH Key Management”页面：
1. 点击右上角头像 → Settings → 左侧菜单 SSH and GPG keys → 点击 New SSH key。
![](images/image20.png)![](images/image21.png)
![](images/image20.png)![](images/image21.png)
2. 输入任何标题（例如，your local computer's SSH），然后将你刚刚获取的 SSH 公钥粘贴到这里。
![](images/image22.png)
@@ -234,8 +234,8 @@ SSH 认证依赖于密钥对（公钥 + 私钥），它们是匹配的加密文
ssh -T git@github.com
```
* 如果你看到类似 Hi [your GitHub username]! You've successfully authenticated... 的内容，说明你已成功绑定密钥；
* 如果遇到错误，通常是因为公钥复制不完整、私钥权限过高（你的本地 ~/.ssh/ 目录应仅由你读写）等。根据需要检查这些问题。
- 如果你看到类似 Hi [your GitHub username]! You've successfully authenticated... 的内容，说明你已成功绑定密钥；
- 如果遇到错误，通常是因为公钥复制不完整、私钥权限过高（你的本地 ~/.ssh/ 目录应仅由你读写）等。根据需要检查这些问题。
### 重要注意事项
@@ -275,5 +275,5 @@ prompt:`I finished. Commit and push to the repository AIID-TEST in ./AIID-TEST.`
# 参考资料
* Pro Git book https://git-scm.com/book/en/v2
* GitHub Docs https://docs.github.com/en
- Pro Git book https://git-scm.com/book/en/v2
- GitHub Docs https://docs.github.com/en
docs/extra/extra2/extra2-what-is-api.md
+44 -39
View File
@@ -6,19 +6,19 @@
为了解决这些痛点，本篇手册以“API 核心逻辑”为整理思路。在这本手册里，我们想做的不是堆名词，而是帮你快速搞清楚三件事：**“这件事可以用什么 API 做？它的本质逻辑是什么？接下来该怎么安全地调用它？”** 通过从生活类比到代码实践的系统梳理，我们将为你揭开 API 的神秘面纱，帮你建立起从“逻辑认知”到“场景映射”再到“代码实现”的完整链路。
> 由于 **内容较多** ，你可以在实践过程中遇到场景不知道如何选型的问题再查阅手册寻找参考；推荐你**根据具体应用方向，让 AI 参考该手册，给出可参考的模型选型建议、方案 API 调用建议即可。**
>
> 如果你只想了解对应的类别，不想看具体内容，只需要看每个大章节的初始段内容即可，例如 1 、2 的内容，但不需要看 5.1 或者 5.2 的代码细节。
>
> **推荐本手册只在需要时查阅对应部分或只浏览一级目录部分，若有兴趣再浏览全文。**
>
> **之后更新会在每个章节部分，推荐可尝试使用的模型 API 服务地址。**
> 由于 **内容较多** ，你可以在实践过程中遇到场景不知道如何选型的问题再查阅手册寻找参考；推荐你**根据具体应用方向，让 AI 参考该手册，给出可参考的模型选型建议、方案 API 调用建议即可。**
>
> 如果你只想了解对应的类别，不想看具体内容，只需要看每个大章节的初始段内容即可，例如 1 、2 的内容，但不需要看 5.1 或者 5.2 的代码细节。
>
> **推荐本手册只在需要时查阅对应部分或只浏览一级目录部分，若有兴趣再浏览全文。**
>
> **之后更新会在每个章节部分，推荐可尝试使用的模型 API 服务地址。**
# 本节课你将学到
* **核心概念映射**：通过“电源插座”与“餐厅点餐”等经典类比，建立对 API 请求与响应循环的直观理解。
* **现实场景解析**：了解天气、地图、社交登录及大语言模型等主流 API 的工作原理，掌握从“功能”到“接口”的映射方法。
* **代码实践与安全**：掌握 Python 环境下 AI API 的调用方式，并理解前端开发中后端代理等安全工程实践的重要性。
- **核心概念映射**：通过“电源插座”与“餐厅点餐”等经典类比，建立对 API 请求与响应循环的直观理解。
- **现实场景解析**：了解天气、地图、社交登录及大语言模型等主流 API 的工作原理，掌握从“功能”到“接口”的映射方法。
- **代码实践与安全**：掌握 Python 环境下 AI API 的调用方式，并理解前端开发中后端代理等安全工程实践的重要性。
完成本手册的学习后，你将对主流 API 能力建立起入门级的系统化认知，不仅知道“市面上有哪些接口、常配哪些产品”，更能理解它们在整体架构中的位置和相互关系。知道在面对具体业务需求时，如何快速定位所需能力、做出有依据的选型，为构建 AI 应用体系打下坚实基础。
@@ -51,28 +51,28 @@ API 无处不在，在后台默默工作。
**天气预报 API**
它就像一个专门提供气象信息的窗口。你的天气应用向它发送坐标和密钥，它就回传一串 JSON 数据。
* **一个简单的“请求”示例：**
* **Endpoint:** `/current-weather`
* **Parameters:** `city=London` & `apiKey=your_access_key`
* **“响应”（回传的数据）：**
```json
- **一个简单的“请求”示例：**
- **Endpoint:** `/current-weather`
- **Parameters:** `city=London` & `apiKey=your_access_key`
- **“响应”（回传的数据）：**
`json
{
"city": "London",
"temperature": "15°C",
"condition": "Cloudy",
"humidity": "70%"
}
```
应用拿到这些数据后，再把它们漂亮地展示在你的手机屏幕上。
`
应用拿到这些数据后，再把它们漂亮地展示在你的手机屏幕上。
**地图服务 API**
不管是外卖平台还是打车软件，它们本身并不生产地图。它们通过调用高德或 Google Maps 的 API，就能获得精准的路线规划和导航功能。
* **一个简单的“请求”示例：**
* **Endpoint:** `/directions`
* **Parameters:** `origin=Eiffel Tower` & `destination=Louvre Museum` & `mode=driving`
* **“响应”（回传的数据）：**
```json
- **一个简单的“请求”示例：**
- **Endpoint:** `/directions`
- **Parameters:** `origin=Eiffel Tower` & `destination=Louvre Museum` & `mode=driving`
- **“响应”（回传的数据）：**
`json
{
"total_distance": "4.5 kilometers",
"estimated_time": "15 minutes",
@@ -82,8 +82,8 @@ API 无处不在，在后台默默工作。
"..."
]
}
```
通过这些数据，应用就能在地图上绘制路线并提供导航指令。
`
通过这些数据，应用就能在地图上绘制路线并提供导航指令。
**社交媒体登录 API**
当你点击“使用 Google 登录"时，购物应用会问 Google API：“这个用户是谁？”Google 验证后告诉应用：“他是 John Doe”。这样，你不用输入密码就能安全登录。
@@ -96,6 +96,7 @@ API 无处不在，在后台默默工作。
当你真正开始动手写代码时，会遇到一些技术名词。别担心，你不需要现在就记住所有细节，只需要看看它们在代码里是怎么“呼吸”的。
### 5.1 Python 中的 AI 调用
在 Python 中调用 OpenAI 的 API 非常直观。你可以通过设置 `base_url` 来指定服务器地址。
```python
@@ -119,37 +120,39 @@ print(response.choices[0].message["content"])
许多模型（如 DeepSeek）都兼容 OpenAI 的格式。你只需要更换 API 密钥和地址，就能无缝切换。
### 5.2 前端开发中的安全实践
如果你在做网页，切记不要在浏览器代码里直接写 API 密钥，否则会被人偷走。通常的做法是写一个**后端代理**，让服务器去替你完成调用。
```javascript
// 后端 Node.js 示例
const express = require("express");
const axios = require("axios");
const app = express();
app.use(express.json());
const express = require('express')
const axios = require('axios')
const app = express()
app.use(express.json())
app.post("/api/chat", async (req, res) => {
app.post('/api/chat', async (req, res) => {
try {
const response = await axios.post(
"https://api.openai.com/v1/chat/completions",
'https://api.openai.com/v1/chat/completions',
{
model: "gpt-3.5-turbo",
messages: [{ role: "user", content: req.body.message }]
model: 'gpt-3.5-turbo',
messages: [{ role: 'user', content: req.body.message }]
},
{
headers: { "Authorization": `Bearer ${process.env.OPENAI_API_KEY}` }
headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` }
}
);
res.json({ reply: response.data.choices[0].message.content });
)
res.json({ reply: response.data.choices[0].message.content })
} catch (error) {
res.status(500).json({ error: error.message });
res.status(500).json({ error: error.message })
}
});
})
app.listen(3001, () => console.log("服务器运行在 3001 端口"));
app.listen(3001, () => console.log('服务器运行在 3001 端口'))
```
你可以使用 `curl` 命令来测试这个接口：
```bash
curl -X POST http://localhost:3001/api/chat \
-H "Content-Type: application/json" \
@@ -161,5 +164,7 @@ curl -X POST http://localhost:3001/api/chat \
API 是现代数字世界的基石。通过理解“请求与响应”这个简单的逻辑，你已经迈出了通往软件开发广阔世界的第一步。在接下来的 Z.ai 探索中，我们将亲手尝试这些调用，感受 AI API 的魅力。
---
**参考资料**
* [Postman: What is an API?](https://www.postman.com/what-is-an-api/)
- [Postman: What is an API?](https://www.postman.com/what-is-an-api/)
docs/extra/extra3/extra3-ai-capability-starter-handbook.md
+2 -3266
View File
File diff suppressed because it is too large Load Diff
docs/extra/extra4/extra4-what-is-ai-ide-and-trae.md
-168
View File
@@ -1,168 +0,0 @@
# 扩展知识 4 - 什么是 AI IDE 和 Trae
在之前的学习阶段，我们使用 z.ai 搭建了最简单的 Web 程序和网页小游戏。但如果我们想要构建更复杂的应用——比如功能更完善的网站、桌面程序，甚至是手机应用——就必须在自己的电脑上使用专业的编程软件来编写代码。
最早的时候，只需要在一个简单的文本文件里写好程序，再用专门的语言处理器去读取并打包执行就够了。但随着代码量越来越大、项目结构越来越复杂，人工管理大量文件、手动编辑庞大的项目变得越来越困难。开发者因此迫切需要一种工具，能够高效管理和切换大量代码文件，支持多种编程语言的语法高亮，并可以快速定位和调试问题。于是，集成开发环境（IDE，Integrated Development Environment）就应运而生了。
你可以把 IDE 理解成一种专门用来“编辑、管理、运行和调试”各种应用源代码的程序。在真正打包发布之前，不同语言写出来的程序本质上只是特定格式的代码文件而已，你可以用普通文本编辑器打开它们，也可以用 IDE 打开。早期的计算机几乎完全通过终端来操作（只用键盘就能完成所有操作，几乎不需要鼠标），所以早期的 IDE 外观也非常“原始”——除非你额外安装插件来实现简单的交互式界面。
![](images/image1.png)![](images/image2.png)
终端界面（Terminal）
图片来源：https://en.wikipedia.org/wiki/File:Emacs-screenshot.png
一个非常知名、功能成熟的“内置 IDE”叫做 `Vim`。在很多服务器上，你都可以直接用它来编辑文件（服务器通常没有显示屏，只能通过键盘远程操作）。
![](images/image3.png)
现代 IDE 通常具有更加美观直观的图形界面，并提供更强大的编辑、运行和调试能力。一个典型的 IDE 通常包含以下核心组件：
* **源代码编辑器（Source Code Editor）**：专门用于编写和编辑代码的文本编辑器，一般具备语法高亮、代码自动补全、实时错误提示等功能。
* **构建与运行工具（编译器 / 解释器）**：IDE 内置编译器或解释器，可以将开发者写好的源代码转换成计算机可以执行的机器代码。
* **调试器（Debugger）**：用于测试和排查代码错误的工具。它支持逐行执行代码、查看变量状态、设置断点等，帮助开发者定位并修复程序中的问题。
除此之外，现代 IDE 往往还内置版本控制工具（如 Git）和项目管理工具等实用功能。当下最流行的 IDE 之一是微软出品的 **[Visual Studio Code (VS Code)](https://code.visualstudio.com/)**。它轻量、可扩展性极强，因此被广泛使用。当然，也有很多开发者推荐 JetBrains 家的专业 IDE，比如用于 Python 的 PyCharm、用于 C/C++ 的 CLion 等，它们对特定语言提供了更深入、更完整的支持。但从入门友好度和通用性角度出发，我们更推荐初学者优先选择 VS Code 作为主要开发工具。
![](images/image4.png)
# 现代 IDE：VS Code
Visual Studio Code（简称 VS Code）是由微软开发的一款免费、开源且功能强大的现代代码编辑器。自 2015 年发布以来，凭借优异的性能和灵活性，它迅速成为全球最受欢迎的开发工具之一。
VS Code 的核心理念之一是“一切皆插件”。不同编程语言可以用来编写不同类型的程序，而每种语言都有自己独特的语法高亮规则和导航能力（比如“跳转到定义”“查找引用”等）。要让一个 IDE 原生支持所有语言几乎是不可能的——从逻辑上讲，你会需要为每一种语言单独准备一个 IDE 才行。
VS Code 巧妙地通过“插件机制”解决了这一问题。比如，如果你要写 Python，就安装 Python 插件，它会提供 Python 专属的语法高亮、自动补全和代码导航功能；如果你要写 C/C++，则可以安装对应的 C/C++ 插件来获得相应支持。在不安装任何插件的情况下，VS Code 本质上只是一个“高级的文本文件管理器”；当你为某种语言安装了对应插件之后，它就会“变身”成该语言的理想开发工具。
![](images/image5.png)
除了编写代码以外，你甚至可以把 VS Code 当作编辑 Markdown 文档的工具来使用。
![](images/image6.png)
总之，你可以在 VS Code 的扩展市场中浏览和下载各类扩展，为不同类型的文件提供更好用的编辑体验，也可以根据需要搜索不同语言和调试工具的插件，尝试它们如何提升你的工作效率。
# 现代 AI IDE
上面介绍的都属于“传统意义上的现代 IDE”。但随着人工智能时代的到来，越来越多的代码开始由大语言模型来自动生成，这自然催生出一种新的开发工具形态——AI IDE，也就是可以利用大语言模型自动写代码的 IDE。
在最新版 VS Code 中，已经内置了一个大语言模型助手。你可以直接针对整个代码仓库、某个文件，甚至某个函数与模型对话。
你也可以像之前在 Web 端使用自动写代码工具一样，将需求以提示词的形式发给内置的编码 Agent，让它自动帮你实现所需功能、创建文件、修改代码、配置环境等。
典型的 AI IDE 一般具备以下核心能力：
* 智能代码生成与补全：在传统 IDE 中，我们通常是输入几个字符来补全变量名或函数名；在现代 AI IDE 中，你可以写几行伪代码或者简单说明需求，让 IDE 自动补全完整的逻辑，甚至根据指令直接生成一大段甚至整块代码。
* 代码理解与问答：IDE 能够理解并回答关于某段代码、某个文件，甚至整个工程目录结构的问题。
* 代码重构与优化：IDE 可以根据你的意图，重写或优化指定代码片段的实现逻辑。
* 自动生成测试：IDE 可以自动生成针对不同函数和模块的测试代码，方便你进行有针对性的测试。
* Agent 式任务执行：智能 Agent 可以自动生成、打包、安装、运行和修改代码，在很多任务上可以部分替代初级软件工程师的工作。
在最新版 VS Code 中，你可以点击右上角的侧边栏入口，打开 AI 功能区域，体验这些能力。
![](images/image7.png)
不过，VS Code 并不是 AI 能力最强的 IDE。对于需要大量 AI 辅助编码的场景，我们往往希望使用“更聪明、效率更高”的工具——好的 AI IDE 能显著节省写代码和改 Bug 的时间。下面我们会介绍几款目前比较流行的 AI IDE，重点讲解 Trae IDE。你可以根据个人喜好选择任意一款 AI IDE 使用。
由于 VS Code 是开源的（任何人都可以下载源码并自行编译），目前市面上绝大多数 AI IDE 都是在 VS Code 基础上二次开发而来。所以你不必担心要“学习很多种 IDE”——一旦你熟悉了 VS Code 的基本用法，迁移到这些 AI IDE 基本不需要重新学习。
如果要简单概括这些 AI IDE 之间的差异，主要集中在四个方面：价格；可使用的模型种类（部分高级模型在某些地区可能受限）；Agent 的能力（在协助写代码时的智能程度和执行能力）；以及运行速度与性能。
## Trae
![](images/image8.png)
Trae 是字节跳动推出的一款 AI 编程助手，支持 100 多种编程语言，并能集成到主流 IDE 中。它的功能包括：用自然语言生成代码、自动调试、把设计稿转换为 React/Vue 组件等。在 2025 年 8 月的更新之后，Trae 新增了智能依赖导入、重命名建议、任务清单管理等功能；SOLO 模式也开始支持后端代码生成和技术架构文档编辑。
## Cursor
Cursor 是 Anysphere 开发的一款 AI 代码编辑器，基于 VS Code 定制，重点优化了大规模代码仓库和多文件协同的场景。它支持 GPT-4o、Claude 3.7 等模型；2025 年推出的 Claude Max 模式可以处理数百万行代码级别的项目。专业版取消了请求次数限制，非常适合复杂的企业级项目。
目前，Cursor 可以说是“带前端界面的 AI IDE”中综合体验最好的一款之一，用户数量庞大，功能迭代频率也很高。它最大的缺点是价格较高——专业版大约需要每月 20 美元。
![](images/image9.png)
## Qoder
Qoder 是阿里巴巴推出的一款强调“透明协作”和“增强上下文工程能力”的 AI IDE。它通过 Action Flow 支持把任务拆解成多个步骤，并实时跟踪 AI 的执行过程；还支持多模型动态路由和任务状态机管理，非常适合在中大型项目中做架构治理和对遗留系统进行“反向工程”分析。
![](images/image10.png)
## CodeBuddy
CodeBuddy 是腾讯云推出的一款 AI 编程工具，强调对中文指令的支持以及企业级合规能力。它提供代码补全、批量代码审查和多模型切换等功能；其中的 Craft 智能体可以实现多文件代码生成和 API 集成。企业版支持私有化部署，并通过了三级等保认证，适合金融、医疗等对数据安全要求较高的行业。
![](images/image11.png)
## windsurf（已不推荐）
Windsurf 最初因其基于 Agent 的 AI 编程能力而受到关注。但由于 2024 年团队调整以及模型权限问题，它的稳定性大幅下降，目前已经不再推荐使用。尽管在前一年它还可以与 Cursor 分庭抗礼，但现在基本可以视为“被淘汰”的工具。
![](images/image12.png)
## VS Code + Cline
Cline 是 VS Code（Visual Studio Code）的一款 AI 编程 Agent 插件，可以通过配置不同的 API 端点来灵活切换所使用的大模型。Cline 支持多模态输入、MCP 工具扩展以及成本监控，所有操作都需要用户确认后才会执行。它非常适合用于快速验证想法，或与现有开发流程集成。基础功能是免费的，企业版则支持在私有环境中部署模型。
![](images/image13.png)
![](images/image14.png)
# 什么是 Trae
Trae 的全称可以理解为 “The Real AI Engineer”，是一款由字节跳动开发的自适应 AI 集成开发环境（IDE）。它是在流行的 VS Code 基础之上构建的，这意味着，如果你之前已经习惯了 VS Code，那么在使用 Trae 时，无论是界面布局还是基础操作都会感到非常熟悉、舒适。
Trae 的核心目标是成为开发者的“智能编程伙伴”。通过深度集成 AI 能力，它可以自动处理大量重复性工作，为你提供更直观、更高效的开发体验。它并不仅仅是一个“代码补全工具”，而是希望贯穿整个开发工作流，从创建项目、编写代码、调试、测试到部署都提供帮助。
## 安装 Trae
Trae 分为国际版和中国版。国际版需要能够访问海外网络，但可以使用 GPT-5、Claude 4 等最新的海外模型；中国版则主要支持国内最新的大模型，例如 GLM、Qwen、Kimi 等。
国际版下载地址：
https://www.trae.ai/
![](images/image15.png)
中国版下载地址：
https://www.trae.cn/
![](images/image16.png)
## Trae 界面简介
简单来说，Trae 和 VS Code 看起来几乎一模一样。
![](images/image17.png)
右侧的侧边栏就是 Copilot 交互窗口，也可以理解为 Agent 窗口。如果你暂时看不到它，可以点击 Trae 右上角的侧边栏图标将其打开。
![](images/image18.png)
打开侧边栏之后，你会看到一个 `Builder` 选项，这就是 Agent 模式。简单理解，它相当于 z.ai 的“本地版”，可以帮你操作本机环境，安装运行环境、打开网页等。
![](images/image19.png)
点击 “Builder” 后，你会看到 “Chat” 模式和 “Builder with MCP” 模式：
* **Chat 模式**：主要用于和当前文件夹里的代码对话，或者当作普通聊天模型来使用。（你可以通过左上角的 “File” 菜单打开一个文件夹，在这个文件夹中进行编辑操作。在这种情况下，Builder 创建或修改的文件都只会发生在这个文件夹内部。）
* **Builder with MCP 模式**：为 Agent 提供了更多可用工具（例如把语言模型和其他软件联通起来、查询天气等）。你可以简单理解为：MCP 能让语言模型更方便地调用各种外部工具。
![](images/image20.png)
在下面的区域，你还会看到模型选择选项，点击即可修改当前使用的大模型。在中国版中，你可以选择使用 Kimi k2 或 GLM 等国内模型；如果你使用的是国际版 Trae，还可以选择 ChatGPT 或 Claude 等海外模型。不过，由于国内大模型发展非常快，Kimi、Qwen、GLM 等在很多任务上的实际体验已经接近 Claude 3.5 或 3.7，对日常开发来说已经完全够用。
![](images/image21.png)
以上就是对 Trae 的一个简单介绍。接下来，我们可以回顾一下之前在 z.ai 中做过的操作，并尝试在 Trae 中做同样的事情。
## 使用 Trae 安装 Python 和前端环境
大多数情况下，我们的 Windows 笔记本电脑默认不会预装前端开发所需的 Node.js 环境，或用于后端 / 通用开发的 Python 环境。我们可以尝试直接在 Trae 的 Agent 模式中跟它对话，让它帮我们安装 Python 环境或 Node.js 环境。
![](images/image22.png)
## 📚 作业：用 Trae 写你的第一个程序
接下来，请尝试用 Trae 来完成你的第一个程序！你还记得之前的 AI 贪吃蛇游戏吗？把当时在 z.ai 中使用的那条提示词原封不动地输入到 Trae 的 Agent 模式中，看看会发生什么吧！
docs/extra/extra4/images/image1.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 103 KiB

docs/extra/extra4/images/image10.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 869 KiB

docs/extra/extra4/images/image11.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 517 KiB

docs/extra/extra4/images/image12.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 692 KiB

docs/extra/extra4/images/image13.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 275 KiB

docs/extra/extra4/images/image14.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 342 KiB

docs/extra/extra4/images/image15.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 43 KiB

docs/extra/extra4/images/image16.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 41 KiB

docs/extra/extra4/images/image17.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 173 KiB

docs/extra/extra4/images/image18.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 82 KiB

docs/extra/extra4/images/image19.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 51 KiB

docs/extra/extra4/images/image2.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 31 KiB

docs/extra/extra4/images/image20.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 26 KiB

docs/extra/extra4/images/image21.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 76 KiB

docs/extra/extra4/images/image22.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 84 KiB

docs/extra/extra4/images/image3.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 112 KiB

docs/extra/extra4/images/image4.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 311 KiB

docs/extra/extra4/images/image5.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 330 KiB

docs/extra/extra4/images/image6.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 242 KiB

docs/extra/extra4/images/image7.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 62 KiB

docs/extra/extra4/images/image8.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 188 KiB

docs/extra/extra4/images/image9.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 578 KiB

docs/extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md
+90 -92
View File
@@ -10,13 +10,13 @@
# 本节课你将学到
* RAG的核心价值：深入理解它如何解决长上下文在成本、注意力、知识更新上的核心难题
* RAG的工作原理：通过具体案例看它如何完成从检索到生成的闭环
* RAG的技术演进脉络：从基础的Naive RAG到Advanced RAG再到模块化的Modular RAG
* RAG的模型选型建议：掌握Embedding、Rerank和LLM三大关键模型的评估与选择策略
* RAG的企业级实践：学习从数据预处理到系统上线评估的全链路构建指南
* RAG的效果评估与调优：了解核心评测指标、主流框架与持续优化的方法
* RAG的前沿趋势：探索其与智能体、多模态等技术融合的未来方向
- RAG的核心价值：深入理解它如何解决长上下文在成本、注意力、知识更新上的核心难题
- RAG的工作原理：通过具体案例看它如何完成从检索到生成的闭环
- RAG的技术演进脉络：从基础的Naive RAG到Advanced RAG再到模块化的Modular RAG
- RAG的模型选型建议：掌握Embedding、Rerank和LLM三大关键模型的评估与选择策略
- RAG的企业级实践：学习从数据预处理到系统上线评估的全链路构建指南
- RAG的效果评估与调优：了解核心评测指标、主流框架与持续优化的方法
- RAG的前沿趋势：探索其与智能体、多模态等技术融合的未来方向
# 本节课你将收获
@@ -40,7 +40,7 @@
> 上下文（context）从意义上指模型在回答当前问题时所“参考”的背景信息与对话历史；从技术上则是指一次推理时输入给模型的 Token 序列（如 system/user 指令、历史消息、检索片段等）的总和。
>
> “上下文窗口”是这批输入内容的 **容量上限** ：模型一次最多只能“看到”这么多 Token。在当前主流的大模型架构（例如 Transformer）中，这些 Token 会在模型的每一层里彼此做注意力计算、反复参与运算，因此一旦窗口变长、Token 变多，计算量和成本都会成倍甚至指数级增加。
>
3. 计算资源存在大量浪费：绝大多数任务仅需极少量与当前问题高度相关的信息，将全量文档塞入上下文，会造成严重的计算资源闲置与浪费，进而降低系统吞吐量，拖慢响应速度，最终影响用户体验。
4. **注意力与聚焦的问题** ：
大模型虽能 “覆盖” 超长上下文，却无法对每一段信息都实现同等质量的利用。当上下文长度达到一定阈值时，模型会出现明显的 “注意力偏差”：
@@ -83,9 +83,9 @@ RAG（Retrieval-Augmented Generation，检索增强生成）的核心思路是
在图中，这一阶段对应右上角紫色区域 “Indexing”。从 “Documents” 出发，经由 “Chunks / Vectors” 到 “embeddings” 的那一部分，就是在说明文档被切块并转换为向量、写入索引的过程。具体过程如下：
* 文档被划分为若干个语义相对完整的 chunks，每个 chunk 可能对应一小段新闻、一段说明或一段分析。
* 每个 chunk 会通过 embedding 模型转换成高维向量，并存入向量索引中。
* 这个索引支持后续基于相似度的检索，为回答问题提前准备好“可被查阅的知识库”。
- 文档被划分为若干个语义相对完整的 chunks，每个 chunk 可能对应一小段新闻、一段说明或一段分析。
- 每个 chunk 会通过 embedding 模型转换成高维向量，并存入向量索引中。
- 这个索引支持后续基于相似度的检索，为回答问题提前准备好“可被查阅的知识库”。
2. **检索阶段 + 基于检索结果生成答案**
@@ -166,9 +166,9 @@ RAG（Retrieval-Augmented Generation，检索增强生成）的核心思路是
简化示例（实际向量维度高得多，这里仅示意）：
* 文档A向量（关于苹果公司创立）：`[0.85, -0.23, 0.41, -0.56, 0.12, 0.78, ...]`
* 文档B向量（关于水果苹果）：`[-0.12, 0.95, -0.34, 0.67, -0.89, 0.05, ...]`
* 文档C向量（关于iPhone发布）：`[0.79, -0.18, 0.52, -0.61, 0.23, 0.81, ...]`
- 文档A向量（关于苹果公司创立）：`[0.85, -0.23, 0.41, -0.56, 0.12, 0.78, ...]`
- 文档B向量（关于水果苹果）：`[-0.12, 0.95, -0.34, 0.67, -0.89, 0.05, ...]`
- 文档C向量（关于iPhone发布）：`[0.79, -0.18, 0.52, -0.61, 0.23, 0.81, ...]`
相关向量需存入向量数据库（如 Pinecone、Weaviate、FAISS）用于之后的检索召回工作。
@@ -186,9 +186,9 @@ RAG（Retrieval-Augmented Generation，检索增强生成）的核心思路是
接下来系统将进行相似度检索 (Top-K, K=2)操作，计算该查询向量与知识库中所有文档向量的余弦相似度（一种衡量向量方向接近程度的指标）。结果如下：
* 与文档A（公司创立）相似度：0.97（高度相关）
* 与文档C（iPhone发布）相似度：0.88（相关，同属公司主题）
* 与文档B（水果营养）相似度：0.12（几乎不相关）
- 与文档A（公司创立）相似度：0.97（高度相关）
- 与文档C（iPhone发布）相似度：0.88（相关，同属公司主题）
- 与文档B（水果营养）相似度：0.12（几乎不相关）
> Top-K 是向量检索场景中常用的筛选策略，核心含义是 “从所有匹配结果中，按相似度从高到低排序后，选取排名前 K 个的结果”；而 K=2 则是对该策略的具体数值定义，即明确要求系统仅保留相似度排名前 2 的文档向量，过滤掉其余相似度更低的结果，以确保后续仅基于最相关的 2 个文档片段生成答案。
@@ -220,9 +220,9 @@ LLM接收到上述结构化输入后，会遵循系统指令，将“参考信
接下来系统将进行相似度检索 (Top-K, K=2) 操作，计算该查询向量与知识库中所有文档向量的余弦相似度。结果如下：
* 与文档B（水果营养）相似度：0.95（高度相关）
* 与文档C（iPhone发布）相似度：0.18（几乎不相关）
* 与文档A（公司创立）相似度：0.15（几乎不相关）
- 与文档B（水果营养）相似度：0.95（高度相关）
- 与文档C（iPhone发布）相似度：0.18（几乎不相关）
- 与文档A（公司创立）相似度：0.15（几乎不相关）
系统根据相似度分数从高到低，返回 Top‑2 的文档片段作为证据：
@@ -254,9 +254,9 @@ LLM接收到上述结构化输入后，其最终回复将类似：
接下来系统将进行相似度检索 (Top-K, K=2) 操作，计算余弦相似度。由于问题主题与知识库内容无关，整体相似度得分都很低。结果如下：
* 与文档B（水果营养）相似度：0.18（极低）
* 与文档C（iPhone发布）相似度：0.10（几乎不相关）
* 与文档A（公司创立）相似度：0.08（几乎不相关）
- 与文档B（水果营养）相似度：0.18（极低）
- 与文档C（iPhone发布）相似度：0.10（几乎不相关）
- 与文档A（公司创立）相似度：0.08（几乎不相关）
Top-K 仍会返回相似度排名前 K 个结果，但在该场景下，这些结果并不能提供有效证据。实际系统常会结合“最低相似度阈值”直接返回空召回，即没有任何召回的结果，参考信息为 0，以减少无关信息干扰。
@@ -310,48 +310,46 @@ Naive RAG可以理解为基础的 RAG 形态，它在工程上非常直接，典
在检索前，重点是把“存什么”和“怎么问”处理好：
* 在索引端，从固定长度切分演进到语义感知分块与分层索引，例如按章节、小节、段落或句子边界进行切分，辅以滑动窗口和多粒度索引结构。
* 为每个文档块附加丰富的元数据，例如来源、时间、作者、主题、文档类型等，为后续的过滤和排序提供更多维度。
* 在查询端，对用户原始问题进行重写、扩展和拆分，例如通过 Query Rewrite、多路查询（Multi-Query）、子问题分解（Sub-Query）、Step-back Prompting 等方式，将含糊或口语化的问题转换为更利于检索理解的表达。
- 在索引端，从固定长度切分演进到语义感知分块与分层索引，例如按章节、小节、段落或句子边界进行切分，辅以滑动窗口和多粒度索引结构。
- 为每个文档块附加丰富的元数据，例如来源、时间、作者、主题、文档类型等，为后续的过滤和排序提供更多维度。
- 在查询端，对用户原始问题进行重写、扩展和拆分，例如通过 Query Rewrite、多路查询（Multi-Query）、子问题分解（Sub-Query）、Step-back Prompting 等方式，将含糊或口语化的问题转换为更利于检索理解的表达。
> 1. Query Rewrite（查询重写）
>
> 核心是将用户模糊、口语化或不规范的原始查询，转化为检索系统更易理解的标准化表述，补充关键信息、修正歧义。
>
> * 用户原始问题为 “咋查明天北京的天气啊”，会去除 “咋”“啊” 等口语化词汇，补充 “实时”“全天” 等关键限定，重写为 “查询北京市明日全天实时天气”；
> * 用户原始问题为 “推荐好看的电影”，若结合用户历史行为发现其常看悬疑片，会补充 “2024 年高分”“悬疑题材” 等信息，重写为 “推荐 2024 年高分悬疑题材电影”。
> - 用户原始问题为 “咋查明天北京的天气啊”，会去除 “咋”“啊” 等口语化词汇，补充 “实时”“全天” 等关键限定，重写为 “查询北京市明日全天实时天气”；
> - 用户原始问题为 “推荐好看的电影”，若结合用户历史行为发现其常看悬疑片，会补充 “2024 年高分”“悬疑题材” 等信息，重写为 “推荐 2024 年高分悬疑题材电影”。
>
> 2. Multi-Query（多路查询）
>
> 基于原始问题生成多个 “语义相关但角度不同” 的查询语句，避免单一查询遗漏潜在结果，覆盖用户未明确的潜在需求。
>
> * 用户原始问题为 “如何给刚满月的宝宝拍嗝”，会生成聚焦 “姿势” 的查询：“新生儿拍嗝的正确姿势”；
> * 生成聚焦 “防吐奶” 的查询：“满月宝宝拍嗝避免吐奶的方法”；
> * 生成聚焦 “月龄适配” 的查询：“婴儿拍嗝的步骤（0-1 个月）”；
> * 生成聚焦 “新手场景” 的查询：“新手爸妈给满月宝宝拍嗝技巧”。
> - 用户原始问题为 “如何给刚满月的宝宝拍嗝”，会生成聚焦 “姿势” 的查询：“新生儿拍嗝的正确姿势”；
> - 生成聚焦 “防吐奶” 的查询：“满月宝宝拍嗝避免吐奶的方法”；
> - 生成聚焦 “月龄适配” 的查询：“婴儿拍嗝的步骤（0-1 个月）”；
> - 生成聚焦 “新手场景” 的查询：“新手爸妈给满月宝宝拍嗝技巧”。
>
> 3. Sub-Query（子问题分解）
>
> 针对包含多个诉求的复合问题，拆分为独立、简单的子查询，让检索系统针对单一诉求精准匹配数据，避免信息混杂缺失。
>
> * 用户原始复合问题为 “北京到上海的高铁，明天有哪些班次？票价多少？需要坐多久？”，会拆解出聚焦 “班次” 的子查询：“北京市至上海市 明日高铁班次表”；
> * 拆解出聚焦 “票价” 的子查询：“北京到上海高铁 二等座 / 一等座票价”；
> * 拆解出聚焦 “时长” 的子查询：“北京到上海高铁 行驶时长（最快 / 平均）”。
> - 用户原始复合问题为 “北京到上海的高铁，明天有哪些班次？票价多少？需要坐多久？”，会拆解出聚焦 “班次” 的子查询：“北京市至上海市 明日高铁班次表”；
> - 拆解出聚焦 “票价” 的子查询：“北京到上海高铁 二等座 / 一等座票价”；
> - 拆解出聚焦 “时长” 的子查询：“北京到上海高铁 行驶时长（最快 / 平均）”。
>
> 4. Step-back Prompting（回溯提示）
>
> 先生成 “比原始问题更宏观的上位问题”，再基于上位逻辑回推检索方向，解决原始问题因聚焦细节导致的理解偏差。
>
> * 用户原始问题为 “为什么 2024 年某国产新能源汽车品牌的销量突然下降？”，第一步生成宏观上位问题：“影响新能源汽车品牌短期销量波动的核心因素有哪些？”（如产品迭代、竞品动作、政策变化、市场需求等）；
> * 第二步基于上位问题逻辑，生成具体检索方向：“2024 年某国产新能源品牌 产品更新情况”“2024 年新能源汽车市场 竞品定价策略”“2024 年新能源汽车补贴政策调整”。
>
> - 用户原始问题为 “为什么 2024 年某国产新能源汽车品牌的销量突然下降？”，第一步生成宏观上位问题：“影响新能源汽车品牌短期销量波动的核心因素有哪些？”（如产品迭代、竞品动作、政策变化、市场需求等）；
> - 第二步基于上位问题逻辑，生成具体检索方向：“2024 年某国产新能源品牌 产品更新情况”“2024 年新能源汽车市场 竞品定价策略”“2024 年新能源汽车补贴政策调整”。
在检索后，重点是把“取回来的内容”治理好：
* 使用专门的 Rerank 模型或 LLM 对候选文档进行重新排序，确保最关键、最贴近问题的内容优先进入上下文。
- 使用专门的 Rerank 模型或 LLM 对候选文档进行重新排序，确保最关键、最贴近问题的内容优先进入上下文。
> Rerank 模型是信息检索流程中的关键组件，主要用于对 “召回阶段” 初步筛选出的候选结果进行二次排序 —— 它会借助更复杂的语义理解能力（常基于 Transformer 等深度学习架构），分析用户需求与候选结果的深层关联，修正初步排序中可能存在的语义偏差，最终让更贴合用户需求的结果排在更靠前的位置，提升用户获取有效信息的效率。
>
* 对检索结果进行筛选、去重与压缩，去掉明显无关或高度重复的片段，缓解长上下文中部信息被忽略的问题。
* 在必要时，结合轻量的模型微调，使 LLM 更倾向于依据检索证据作答，并在回答中附带引用或出处信息。
- 对检索结果进行筛选、去重与压缩，去掉明显无关或高度重复的片段，缓解长上下文中部信息被忽略的问题。
- 在必要时，结合轻量的模型微调，使 LLM 更倾向于依据检索证据作答，并在回答中附带引用或出处信息。
总体来看，第二代检索增强生成技术其关注点不再局限于 “是否需要检索”“能否检索到信息” 这两个基础问题，而是进一步聚焦于三个更大的挑战：“能否精准定位到真正关键的段落内容”“传递给大模型的上下文是否简洁有序、具备清晰结构且易于高效利用”“当面临信息噪音、内容冲突或多资料源查找需求时，系统整体性能是否依然稳健可靠”。
@@ -452,8 +450,8 @@ MTEB为各类Embedding模型提供了一个统一、客观的评估框架。它
在选择 Embedding 模型时，我们可以用 MTEB 这样的 benchmark。而对于 Rerank 模型我们可以参考 Agentset 的 [Reranker Leaderboard](https://agentset.ai/rerankers)，该网站针对 RAG 场景下的重排能力做了系统测试。
| Model Name↑ | ELO | nDCG@10 | Latency (ms) | Price / 1M | License |
| --------------------------------------------------------------------------------------------------- | ---- | ------- | ------------ | ---------- | ------------ |
| Model Name↑ | ELO | nDCG@10 | Latency (ms) | Price / 1M | License |
| ------------------------------------------------------------------------------------------------------ | ---- | ------- | ------------ | ---------- | ------------ |
| [BAAI/BGE Reranker v2 M3](https://agentset.ai/rerankers/baaibge-reranker-v2-m3) | 1314 | 0.201 | 2383 | $0.02 | Apache 2.0 |
| [Cohere Rerank 3.5](https://agentset.ai/rerankers/cohere-rerank-35) | 1452 | 0.2 | 392 | $0.05 | Proprietary |
| [Cohere Rerank 4 Fast](https://agentset.ai/rerankers/cohere-rerank-4-fast) | 1506 | 0.216 | 447 | $0.05 | Proprietary |
@@ -472,8 +470,8 @@ MTEB为各类Embedding模型提供了一个统一、客观的评估框架。它
在此基础上，基准测试还设计了两组互补性指标，用于对模型进行多维度综合评估：
* nDCG@5/10：聚焦排序精准度，重点衡量相关文档是否被合理置于结果前列，直接反映 “排得准” 的能力；
* Recall@5/10：侧重结果覆盖面，核心评估系统能否识别出所有与查询相关的文档，对应 “找得全” 的能力。
- nDCG@5/10：聚焦排序精准度，重点衡量相关文档是否被合理置于结果前列，直接反映 “排得准” 的能力；
- Recall@5/10：侧重结果覆盖面，核心评估系统能否识别出所有与查询相关的文档，对应 “找得全” 的能力。
这两组指标相辅相成，共同构建起对 Rerank 模型的完整评估体系，确保评估结果更具全面性与参考价值。
@@ -493,8 +491,8 @@ MTEB为各类Embedding模型提供了一个统一、客观的评估框架。它
以下是竞技场排名的示例（截止至 2025 年 12 月 15 日）
| Rank | Model | Score | Votes | Organization | License |
| ---- | ---------------------------------------------------------------------------------------- | ----- | ------ | ------------ | ----------- |
| Rank | Model | Score | Votes | Organization | License |
| ---- | ------------------------------------------------------------------------------------------- | ----- | ------ | ------------ | ----------- |
| 1 | [gemini-3-pro](http://aistudio.google.com/app/prompts/new_chat?model=gemini-3-pro-preview) | 1492 | 15,871 | Google | Proprietary |
| 2 | [grok-4.1-thinking](https://x.ai/news/grok-4-1) | 1478 | 16,660 | xAI | Proprietary |
| 3 | [claude-opus-4-5-20251101-thinking-32k](https://www.anthropic.com/news/claude-opus-4-5) | 1470 | 9,879 | Anthropic | Proprietary |
@@ -516,20 +514,20 @@ LMArena的独特价值在于其评估方式更贴近真实用户体验，而非
在实际工程实践中，通常不需要从零开始构建整个 RAG 系统。目前业界已有多个成熟的开源框架可供选择，它们在架构设计、模块集成和开发效率等方面各有特色。企业可以根据自身的技术储备和业务场景，选择合适的框架快速搭建系统。常见的框架类型包括：
**低代码** **/可视化平台**
**低代码** **/可视化平台**
* [Dify](https://dify.ai)：提供直观的可视化界面，支持快速搭建 RAG 应用，适合非技术团队或快速原型验证场景。内置多模型接入、工作流编排和 prompt 管理功能。
* [Coze](https://www.coze.com/)：字节跳动推出的 AI Bot 开发平台，提供零代码的可视化搭建能力。特色在于与豆包等字节系大模型深度集成，支持插件市场、定时任务和多渠道发布（飞书、微信等），适合快速构建面向 C 端用户的对话应用或企业内部智能助手。
* [n8n](https://n8n.io/)：一个开源的、基于节点的工作流自动化平台。它通过可视化的方式连接各类应用、API和数据源。在RAG场景中，可以利用n8n编排复杂的业务逻辑，将数据预处理、向量数据库操作、大模型调用以及后续动作（如发送邮件、更新工单）串联成一个自动化流程。
* [RAGFlow](https://ragflow.io/)：专注于深度版面分析和知识抽取能力，对复杂文档（如多栏 PDF、表格密集型文档）的处理效果较好，适合文档结构复杂的企业知识库场景。
* [FastGPT](https://fastgpt.io/en)：中国国内开源方案,集成了知识库管理、对话流程编排和应用发布功能，中文文档完善，适合快速部署中文 RAG 应用。
- [Dify](https://dify.ai)：提供直观的可视化界面，支持快速搭建 RAG 应用，适合非技术团队或快速原型验证场景。内置多模型接入、工作流编排和 prompt 管理功能。
- [Coze](https://www.coze.com/)：字节跳动推出的 AI Bot 开发平台，提供零代码的可视化搭建能力。特色在于与豆包等字节系大模型深度集成，支持插件市场、定时任务和多渠道发布（飞书、微信等），适合快速构建面向 C 端用户的对话应用或企业内部智能助手。
- [n8n](https://n8n.io/)：一个开源的、基于节点的工作流自动化平台。它通过可视化的方式连接各类应用、API和数据源。在RAG场景中，可以利用n8n编排复杂的业务逻辑，将数据预处理、向量数据库操作、大模型调用以及后续动作（如发送邮件、更新工单）串联成一个自动化流程。
- [RAGFlow](https://ragflow.io/)：专注于深度版面分析和知识抽取能力，对复杂文档（如多栏 PDF、表格密集型文档）的处理效果较好，适合文档结构复杂的企业知识库场景。
- [FastGPT](https://fastgpt.io/en)：中国国内开源方案,集成了知识库管理、对话流程编排和应用发布功能，中文文档完善，适合快速部署中文 RAG 应用。
**代码框架/开发库**
以下介绍的软件通常都有不同平台（前后端）语言的实现方式，你可以根据当前应用的语言选择下列对应软件的语言版本（例如 Python 或 Java 版）。
* [LlamaIndex](https://www.llamaindex.ai/)：专为 RAG 场景设计的 Python 框架，提供丰富的数据连接器（Connector）、索引结构和查询引擎,模块化程度高,适合需要深度定制检索策略或集成多种数据源的场景。
* [LangChain](https://www.langchain.com/)：通用 LLM 应用开发框架，RAG 只是其中一个应用方向。优势在于生态丰富、组件齐全，支持复杂的 Agent 和工作流编排，但学习曲线相对陡峭,适合构建复杂的多模块 LLM 应用。
- [LlamaIndex](https://www.llamaindex.ai/)：专为 RAG 场景设计的 Python 框架，提供丰富的数据连接器（Connector）、索引结构和查询引擎,模块化程度高,适合需要深度定制检索策略或集成多种数据源的场景。
- [LangChain](https://www.langchain.com/)：通用 LLM 应用开发框架，RAG 只是其中一个应用方向。优势在于生态丰富、组件齐全，支持复杂的 Agent 和工作流编排，但学习曲线相对陡峭,适合构建复杂的多模块 LLM 应用。
如果团队技术储备有限、追求快速上线，可优先考虑 Dify 、Coze 或 FastGPT 等低代码平台；如果需要深度定制检索框架、对接特殊数据源或优化性能细节，LlamaIndex 和 LangChain 提供了更大的灵活性。实际项目中，也可以采用"混合方案"：用低代码平台快速验证可行性，再用代码框架实现生产级部署和性能优化。此外，这些框架大多支持主流 Embedding、Rerank 和 LLM 模型的快速接入，可以基于前文提到的模型选型标准灵活组合最后使用的模型型号。
@@ -543,9 +541,9 @@ LMArena的独特价值在于其评估方式更贴近真实用户体验，而非
具体而言，该流程通常包含三个关键步骤：
* 首先合成评测数据集，我们需要从知识库中采样文档，并指令 LLM 生成与之对应的、高质量的“问题-参考答案”对，再经过相关性、事实 groundedness 等过滤，形成基准测试集；
* 其次，运行 RAG 系统并收集答案，让待评估的系统处理测试集中的每个问题，得到其生成的答案；
* 最后，进行自动化判分，调用另一个作为“裁判”的 LLM，将系统生成的答案与参考答案进行对比，从准确性、完整性等维度给出量化评分。
- 首先合成评测数据集，我们需要从知识库中采样文档，并指令 LLM 生成与之对应的、高质量的“问题-参考答案”对，再经过相关性、事实 groundedness 等过滤，形成基准测试集；
- 其次，运行 RAG 系统并收集答案，让待评估的系统处理测试集中的每个问题，得到其生成的答案；
- 最后，进行自动化判分，调用另一个作为“裁判”的 LLM，将系统生成的答案与参考答案进行对比，从准确性、完整性等维度给出量化评分。
可以用一个简单的例子展示其过程：
@@ -559,8 +557,8 @@ LMArena的独特价值在于其评估方式更贴近真实用户体验，而非
若你需要深入掌握具体细节（如指标的数学计算逻辑、框架的实操部署步骤、不同基准数据集的适用场景等），建议参考以下两篇 RAG 评测领域的论文：
* [https://arxiv.org/pdf/2504.14891](https://arxiv.org/pdf/2504.14891)（《Retrieval Augmented Generation Evaluation in the Era of Large Language Models: A Comprehensive Survey》）：系统梳理了 LLM 时代 RAG 的内外部评测方法，涵盖组件级与系统级评估，还汇总了海量评测数据集与框架，并分析了当前研究趋势与挑战。
* [https://arxiv.org/pdf/2405.07437](https://arxiv.org/pdf/2405.07437)（《Evaluation of Retrieval-Augmented Generation: A Survey》）：提出了统一的 RAG 评测流程（Auepora），从 “评测目标、数据集、指标” 三维度拆解评测逻辑，同时对比了不同基准的优劣，为实践提供了清晰指引。
- [https://arxiv.org/pdf/2504.14891](https://arxiv.org/pdf/2504.14891)（《Retrieval Augmented Generation Evaluation in the Era of Large Language Models: A Comprehensive Survey》）：系统梳理了 LLM 时代 RAG 的内外部评测方法，涵盖组件级与系统级评估，还汇总了海量评测数据集与框架，并分析了当前研究趋势与挑战。
- [https://arxiv.org/pdf/2405.07437](https://arxiv.org/pdf/2405.07437)（《Evaluation of Retrieval-Augmented Generation: A Survey》）：提出了统一的 RAG 评测流程（Auepora），从 “评测目标、数据集、指标” 三维度拆解评测逻辑，同时对比了不同基准的优劣，为实践提供了清晰指引。
### 5.3.2 评测指标
@@ -574,9 +572,9 @@ RAG系统的评估本质上围绕两个核心问题：检索模块能否准确
首先是一组衡量召回基本质量的经典指标：Recall@K、Precision@K和F1。
* **Recall@K** 衡量在前K条检索结果中，相关文档被找回的比例。比如知识库中有5篇相关文档,前10条结果找回了3篇,则Recall@10为60%。这个指标告诉我们检索的"覆盖面"如何。
* **Precision** **@K** 衡量前K条结果中真正相关文档的占比。同样是前10条结果,如果其中有3篇相关、7篇不相关,则Precision@10为30%。这个指标反映检索的"准确度"。
* **F1** 则是Recall和Precision的调和平均,在两者间寻求平衡。
- **Recall@K** 衡量在前K条检索结果中，相关文档被找回的比例。比如知识库中有5篇相关文档,前10条结果找回了3篇,则Recall@10为60%。这个指标告诉我们检索的"覆盖面"如何。
- **Precision** **@K** 衡量前K条结果中真正相关文档的占比。同样是前10条结果,如果其中有3篇相关、7篇不相关,则Precision@10为30%。这个指标反映检索的"准确度"。
- **F1** 则是Recall和Precision的调和平均,在两者间寻求平衡。
这组指标适合快速发现召回阶段的基础问题,比如向量化模型是否有效、检索策略是否合理、Query改写是否到位等。如果Recall很低,说明相关文档根本没被找到;如果Precision很低,说明检索噪声太大。
@@ -584,9 +582,9 @@ RAG系统的评估本质上围绕两个核心问题：检索模块能否准确
找到相关文档只是第一步,更重要的是把最相关的文档排在前面。这就需要关注排序质量的指标：MRR、NDCG@K和MAP。
* **MRR** **(** **Mean Reciprocal Rank** **)** 计算第一个相关文档出现位置的倒数均值。如果第一个相关文档出现在第3位,该条查询的RR就是1/3。MRR适合那些只需要一个正确答案的场景,比如问答系统。
* **NDCG@K(Normalized Discounted Cumulative Gain)** 考虑了相关性分级和位置衰减两个因素。它不仅关注文档是否相关,还关注相关程度;同时,越相关的文档排在越前面,得分越高。这使得NDCG成为衡量排序质量最全面的指标之一。
* **MAP(Mean ** **Average Precision** **)** 综合考虑所有相关文档的位置,对整体排序质量更为敏感。
- **MRR** **(** **Mean Reciprocal Rank** **)** 计算第一个相关文档出现位置的倒数均值。如果第一个相关文档出现在第3位,该条查询的RR就是1/3。MRR适合那些只需要一个正确答案的场景,比如问答系统。
- **NDCG@K(Normalized Discounted Cumulative Gain)** 考虑了相关性分级和位置衰减两个因素。它不仅关注文档是否相关,还关注相关程度;同时,越相关的文档排在越前面,得分越高。这使得NDCG成为衡量排序质量最全面的指标之一。
- **MAP(Mean ** **Average Precision** **)** 综合考虑所有相关文档的位置,对整体排序质量更为敏感。
在实际工程中,我们通常采用 Recall@K + MRR@K 的组合,既保证召回覆盖面又约束排序质量。举个例子,如果发现Recall@10达到80%但MRR@10只有0.3,说明相关文档虽然被找到了但都埋在后面,这时就需要优化重排序策略,比如引入交叉编码器或调整多路召回的权重分配。
@@ -598,11 +596,11 @@ RAG系统的评估本质上围绕两个核心问题：检索模块能否准确
**精确匹配与文本相似度**
最直接的评估方式是 **EM(Exact Match)** ,要求生成答案与参考答案完全一致。这个指标适合答案唯一、形式固定的场景,比如"成立日期是什么时候?""总部在哪里?"这类事实性问答。但EM过于严格,同样正确的"2020年1月1日"和"2020-01-01"会被判为不匹配。
最直接的评估方式是 **EM(Exact Match)** ,要求生成答案与参考答案完全一致。这个指标适合答案唯一、形式固定的场景,比如"成立日期是什么时候?""总部在哪里?"这类事实性问答。但EM过于严格,同样正确的"2020年1月1日"和"2020-01-01"会被判为不匹配。
因此,更常用的是基于n-gram重叠的相似度指标： **ROUGE** **、** **BLEU** **、METEOR** 。它们通过计算生成内容与参考答案的词汇重叠程度来打分。其中,ROUGE-L关注最长公共子序列,对答案的流畅性更敏感;BLEU源自机器翻译领域,注重精确匹配;METEOR则加入了同义词和词干的考量。这些指标的优势是计算简单、易于理解,但也有明显局限——它们只看表面词汇匹配,对语义理解不够深入。
因此,更常用的是基于n-gram重叠的相似度指标： **ROUGE** **、** **BLEU** **、METEOR** 。它们通过计算生成内容与参考答案的词汇重叠程度来打分。其中,ROUGE-L关注最长公共子序列,对答案的流畅性更敏感;BLEU源自机器翻译领域,注重精确匹配;METEOR则加入了同义词和词干的考量。这些指标的优势是计算简单、易于理解,但也有明显局限——它们只看表面词汇匹配,对语义理解不够深入。
为了弥补这一不足,我们可以引入 **BertScore** 或直接的 **向量相似度** 。它们利用预训练模型的向量表示来计算语义相似度,更能容忍表述差异。比如"这款产品很受欢迎"和"该设备广受好评"在词汇上几乎没有重叠,但向量相似度会很高。这对于需要改写、总结、解释的生成任务特别有效。
为了弥补这一不足,我们可以引入 **BertScore** 或直接的 **向量相似度** 。它们利用预训练模型的向量表示来计算语义相似度,更能容忍表述差异。比如"这款产品很受欢迎"和"该设备广受好评"在词汇上几乎没有重叠,但向量相似度会很高。这对于需要改写、总结、解释的生成任务特别有效。
**事实忠实度与幻觉检测**
@@ -618,10 +616,10 @@ RAG系统的评估本质上围绕两个核心问题：检索模块能否准确
具体做法是:将问题、检索文档、系统回答、参考答案一并输入一个独立的大模型(通常选择能力较强的模型如GPT-4或Claude),让它按多个维度进行综合评分：
* **问题相关性** ：答案是否真正回应了用户问题,有没有答非所问?
* **信息完整性** ：该涵盖的要点是否都说到了,有没有遗漏关键信息?
* **事实忠实性** ：答案是否出现了检索文档中不存在的内容,有没有幻觉?
* **整体正确性** ：与参考答案相比,生成答案的质量如何?
- **问题相关性** ：答案是否真正回应了用户问题,有没有答非所问?
- **信息完整性** ：该涵盖的要点是否都说到了,有没有遗漏关键信息?
- **事实忠实性** ：答案是否出现了检索文档中不存在的内容,有没有幻觉?
- **整体正确性** ：与参考答案相比,生成答案的质量如何?
LLM裁判的优势在于能进行更接近人类的整体性判断——它可以理解上下文、把握语义、识别逻辑,甚至能发现一些自动化指标捕捉不到的细微问题,比如语气不当、逻辑矛盾、表述含糊等。当然,裁判本身也需要精心设计prompt,并用人工标注样本进行校准,确保评分标准的一致性和可靠性。
@@ -631,9 +629,9 @@ LLM裁判的优势在于能进行更接近人类的整体性判断——它可
一个务实的建议是 **从精简组合开始,逐步完善** ：
* **检索评估** ：采用 Recall@K + MRR@K 的核心组合,快速把握召回覆盖和排序质量
* **生成评估** ：根据任务特点,从 EM、ROUGE-L、BertScore 中选择一到两个作为基线
* **综合评估** ：引入 LLM裁判,重点关注相关性、完整性、忠实性三个维度
- **检索评估** ：采用 Recall@K + MRR@K 的核心组合,快速把握召回覆盖和排序质量
- **生成评估** ：根据任务特点,从 EM、ROUGE-L、BertScore 中选择一到两个作为基线
- **综合评估** ：引入 LLM裁判,重点关注相关性、完整性、忠实性三个维度
在此基础上,采用"评测→发现问题→调整策略→再评测"的循环迭代。比如,发现召回率不错但MRR很低,就重点优化重排序;发现幻觉率偏高,就加强对检索文档的忠实度约束;发现某些类型的问题回答质量不好,就针对性地补充细分指标。
@@ -649,13 +647,13 @@ LLM裁判的优势在于能进行更接近人类的整体性判断——它可
**研究型框架**主要服务于学术研究和前沿探索,特点是评测维度细致、方法创新性强。代表性的如FiD-Light和Diversity Reranker,它们专注于检索阶段的细粒度评估,前者关注召回的延迟性(Latency),后者强调结果的多样性(Diversity)。这类框架通常会深入到RAG系统的某个特定环节,提供精细化的诊断能力。
**基准测试****框架**则提供了标准化的测试集和评测流程,用于横向比较不同RAG系统的性能。这类框架数量最多、影响最广。例如：
**基准测试\*\***框架\*\*则提供了标准化的测试集和评测流程,用于横向比较不同RAG系统的性能。这类框架数量最多、影响最广。例如：
* **RAGAS** （2023.09）是最早的综合性RAG评测框架之一,采用LLM-as-a-Judge模式,同时评估检索和生成两个环节
* **ARES** （2023.11）引入了分类器辅助的评测方法,结合LLM判断和传统分类器来评估Context相关性和Answer相关性
* **RGB** （2023.12）专注于生成阶段的评估,提出了信息整合(Info Integration)、噪声鲁棒性(NoiseRobust)、负样本拒绝(NegRejection)、反事实鲁棒性(Counterfact)等细分维度
* **MultiHop-RAG** （2024.01）针对多跳推理场景,重点评估检索的相关性(Retrieval C)和回答的正确性(Response C),使用MAP、MRR、Hit@K等指标
* **CRUD-RAG** （2024.02）模拟真实的知识管理场景,评估系统在Create、Read、Update、Delete四种操作下的表现,引入了RAGQuerEval评分体系
- **RAGAS** （2023.09）是最早的综合性RAG评测框架之一,采用LLM-as-a-Judge模式,同时评估检索和生成两个环节
- **ARES** （2023.11）引入了分类器辅助的评测方法,结合LLM判断和传统分类器来评估Context相关性和Answer相关性
- **RGB** （2023.12）专注于生成阶段的评估,提出了信息整合(Info Integration)、噪声鲁棒性(NoiseRobust)、负样本拒绝(NegRejection)、反事实鲁棒性(Counterfact)等细分维度
- **MultiHop-RAG** （2024.01）针对多跳推理场景,重点评估检索的相关性(Retrieval C)和回答的正确性(Response C),使用MAP、MRR、Hit@K等指标
- **CRUD-RAG** （2024.02）模拟真实的知识管理场景,评估系统在Create、Read、Update、Delete四种操作下的表现,引入了RAGQuerEval评分体系
进入2024年后,评测框架呈现出明显的专业化和细分化趋势。医疗领域有MedRAG,法律领域有LegalBench-RAG,金融领域有相关的domain-specific框架。这些领域框架不仅提供了专业数据集,还针对行业特点设计了定制化的评测指标,比如医疗场景特别关注准确性(Accuracy),法律场景强调文档级精确度(Doc-level Precision)和引用相关性(Citation Relevance)。
@@ -663,9 +661,9 @@ LLM裁判的优势在于能进行更接近人类的整体性判断——它可
上述我们介绍了多种不同的 RAG 评测框架，但在具体实战中该如何选择？不妨先选取 GitHub 星标数量较多的几款进行初步测试；而当企业面临丰富的框架选择、需要落地决策时，可从以下几方面着手。
* 快速上手需求：若需快速搭建基线评测，可选择 RAGAS、RAGEval 等综合性框架，它们能提供开箱即用的完整流程，若需深入诊断某一环节问题，则需选用针对性框架 ：例如检索效果不佳时可用 MultiHop-RAG，幻觉问题突出时则可采用 CoURAGE 或 RAG Unfairness。
* 结合行业进行选择：若应用于医疗、法律、金融等专业领域，应优先选择适配该领域的框架，这类框架往往内置专业术语处理、合规性检查等关键能力，通用框架虽功能全面，但在专业场景中易出现 “水土不服” 的情况。
* 根据集成成本选择：像 LangChain Benchmarks、TruEra RAG Triad 等框架已与主流开发框架深度集成，能快速接入现有系统，而部分学术框架虽技术方法先进，却需额外投入工程适配工作；最后需关注持续维护情况，应优先选择社区活跃、文档完善且持续更新的框架，避开已停止维护的项目，具体可参考 GitHub 星标数量、更新频率、Issue 响应速度等指标。
- 快速上手需求：若需快速搭建基线评测，可选择 RAGAS、RAGEval 等综合性框架，它们能提供开箱即用的完整流程，若需深入诊断某一环节问题，则需选用针对性框架 ：例如检索效果不佳时可用 MultiHop-RAG，幻觉问题突出时则可采用 CoURAGE 或 RAG Unfairness。
- 结合行业进行选择：若应用于医疗、法律、金融等专业领域，应优先选择适配该领域的框架，这类框架往往内置专业术语处理、合规性检查等关键能力，通用框架虽功能全面，但在专业场景中易出现 “水土不服” 的情况。
- 根据集成成本选择：像 LangChain Benchmarks、TruEra RAG Triad 等框架已与主流开发框架深度集成，能快速接入现有系统，而部分学术框架虽技术方法先进，却需额外投入工程适配工作；最后需关注持续维护情况，应优先选择社区活跃、文档完善且持续更新的框架，避开已停止维护的项目，具体可参考 GitHub 星标数量、更新频率、Issue 响应速度等指标。
除此之外，在社区中还公认推荐了一批工具，部分框架已在上述内容中提到：Ragas 提供了丰富指标且不绑定特定框架；Continuous Eval 以轻量和低成本为特点，支持构建具备数学保证的评估流水线；TruLens‑Eval 与 LangChain、Llama‑Index 等主流框架集成良好，并提供可视化分析；而 Llama‑Index 自身生态中也集成了评估与合成数据生成功能，便于对其构建的应用进行闭环测试。还有 Phoenix、DeepEval、LangSmith 和 OpenAI Evals 等工具也在持续迭代中，你可综合自身需求和对应工具的口碑进一步选用。
@@ -677,9 +675,9 @@ LLM裁判的优势在于能进行更接近人类的整体性判断——它可
对于大多数企业而言，由于业务场景存在独特性，最终往往需要构建自己的评测数据集。
* 构建过程可以从业务日志中提取真实用户问题入手，并依据类型、频率和难度进行分层采样，以保证数据的代表性。对于简单问题可由领域专家直接标注,复杂问题则可先用高质量LLM生成候选答案,再由专家审核修改,这种"机器生成+人工校准"的方式能显著降低标注成本。
* 除答案本身,标注相关文档、答案类型、难度等级等元信息,为后续细分析提供支持。建立标注规范,进行多人交叉验证,计算标注一致性(如Kappa系数),确保数据质量。
* 定期从线上反馈中补充新的测试用例,尤其是系统回答不好的问题,让评测数据与系统能力同步演进。这种持续迭代的机制能让评测基准始终保持对业务场景的敏感度和有效性。
- 构建过程可以从业务日志中提取真实用户问题入手，并依据类型、频率和难度进行分层采样，以保证数据的代表性。对于简单问题可由领域专家直接标注,复杂问题则可先用高质量LLM生成候选答案,再由专家审核修改,这种"机器生成+人工校准"的方式能显著降低标注成本。
- 除答案本身,标注相关文档、答案类型、难度等级等元信息,为后续细分析提供支持。建立标注规范,进行多人交叉验证,计算标注一致性(如Kappa系数),确保数据质量。
- 定期从线上反馈中补充新的测试用例,尤其是系统回答不好的问题,让评测数据与系统能力同步演进。这种持续迭代的机制能让评测基准始终保持对业务场景的敏感度和有效性。
当然，如果团队资源有限或希望快速建立基线，参考业界成熟的公开评测基准也是一个可行的起点。截至2025年，已有诸多涵盖通用领域和垂直行业的基准可供选择（见图表）。
@@ -846,9 +844,9 @@ RAG技术已从最初的检索增强生成工具，发展为构建智能体认
Agentic RAG实现上述复杂任务处理的关键，在于其建立了一个多层次的主动循环工作机制。 面对复杂查询，智能体首先分析问题本质，将其拆解为子问题，并为每个子问题设计精准的检索策略。获得初步结果后，智能体进行评估与反思，判断信息的完整性和相关性，识别知识缺口，并动态生成更精确的新查询。这种迭代过程常包含多跳检索，即基于前一轮结果发现新的检索方向，形成类似人类研究者的知识探索链条。然而，要支撑这种持续的、迭代的智能行为，尤其是实现长期交互中的个性化和知识积累，仅依赖单次会话的短期上下文（短期记忆）是远远不够的。这引出了对长期、结构化记忆能力的需求。
正是为了满足这一需求，RAG被赋予了作为智能体长期记忆系统的角色，构建了一个完整的外部记忆架构。 该系统与负责维护当前会话上下文的短期记忆形成互补。该长期记忆系统的核心运作依赖于三项关键机制：
第一，结构化索引能力：使智能体能够为海量非结构化数据建立多维索引体系（如按时间、主题或实体关系），支持多角度高效检索，模拟人脑通过不同线索回忆信息的方式。
第二，智能遗忘机制：通过价值评估算法，系统对使用频率低、相关性弱或过时的信息进行权重衰减或选择性剔除，维持记忆系统的精炼高效，防止信息过载。
第三，知识巩固过程：系统将零散对话和交互经验提炼为结构化知识，利用实体识别、关系抽取和语义聚类等技术，将碎片信息整合连接成知识图谱，完成从短期经验到长期知识的转化与沉淀。
第一，结构化索引能力：使智能体能够为海量非结构化数据建立多维索引体系（如按时间、主题或实体关系），支持多角度高效检索，模拟人脑通过不同线索回忆信息的方式。
第二，智能遗忘机制：通过价值评估算法，系统对使用频率低、相关性弱或过时的信息进行权重衰减或选择性剔除，维持记忆系统的精炼高效，防止信息过载。
第三，知识巩固过程：系统将零散对话和交互经验提炼为结构化知识，利用实体识别、关系抽取和语义聚类等技术，将碎片信息整合连接成知识图谱，完成从短期经验到长期知识的转化与沉淀。
这种由RAG构建的外部记忆系统，不仅极大地扩展了智能体的认知边界，更重要的是赋予了其持续学习和知识进化的能力。 它使得智能体能够在长期互动中积累经验，形成个性化的处理模式和领域专业知识体系，从而为执行更复杂、更持久的任务提供了坚实的基础。
docs/extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md
+4 -3
View File
@@ -17,7 +17,7 @@
如果手动部署，一个项目往往需要好几个步骤，每一步都可能踩坑。常见关键步骤包括：
1. **服务器准备**：你需要先购买云服务器（比如阿里云、腾讯云、或 AWS EC2），选择服务器所在地区（如上海、新加坡）、配置（CPU、内存、磁盘大小等），还要学会如何远程连接服务器（例如通过 SSH 工具登录）。
![](images/image2.png)
![](images/image2.png)
2. **环境配置**：Web 应用需要在特定“环境”中才能运行——例如运行 Node.js 项目必须先安装 Node.js；运行 Python 项目必须安装 Python 以及对应的第三方库。如果环境版本不匹配，程序就可能报错、无法启动。
3. **上传资源**：你需要把本地的代码和资源上传到服务器上，常用的方法包括 FTP 或 Git。如果项目体积比较大（比如包含视频文件），中途一旦断线，有时需要重新上传。
@@ -65,8 +65,8 @@
1. **GitHub**
可以连接到你的 GitHub 账号。绑定之后，就可以直接从 GitHub 仓库里选择项目部署（GitHub 是目前全球最大的代码托管平台）。
2. **Template（模板）**
可以基于模板来部署服务。Zeabur 内置了很多预设项目模板（例如 Dify、n8n 等），你可以基于这些模板快速创建并部署应用。
![](images/image9.png)
可以基于模板来部署服务。Zeabur 内置了很多预设项目模板（例如 Dify、n8n 等），你可以基于这些模板快速创建并部署应用。
![](images/image9.png)
3. **Databases（数据库）**
用于部署数据库服务，比如 MySQL、MongoDB 等常见数据库。
![](images/image10.png)
@@ -75,6 +75,7 @@
![](images/image11.png)
![](images/image12.png)
5. **Local Project（本地项目）**
上传一个本地文件夹，Zeabur 会自动识别其中的启动脚本。这适合将你已经在本地开发好的项目快速部署到 Zeabur 上。
![](images/image13.png)
docs/extra/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md
+13 -13
View File
@@ -30,16 +30,16 @@ CLI 天生适合文本命令操作，在一小部分极客（追求极致的编
为了更直观地对比，我们可以简单看看 Claude Code 和某款 AI IDE Agent 的差异（这里以 Cursor 为例）：
| 功能特性 | Claude Code | Cursor | 更优者 |
| ------------------------ | -------------------- | ----------------- | ----------- |
| 自动任务执行 | ✅ 非常强 | ❌ 能力有限 | Claude Code |
| IDE 集成 | ❌ 仅命令行 | ✅ 原生 VS Code | Cursor |
| 实时代码补全 | ❌ 无 | ✅ 体验极佳 | Cursor |
| 多文件操作 | ✅ 非常强 | ⚠️ 还不错 | Claude Code |
| GitHub 一体化操作 | ✅ 可直接提交 | ⚠️ 需要手动操作 | Claude Code |
| 学习成本 | ⚠️ 中等 | ✅ 上手简单 | Cursor |
| 上下文长度 | ✅ 非常长 | ⚠️ 较好 | Claude Code |
| 调试辅助 | ✅ 自动化 | ⚠️ 较多需手动 | Claude Code |
| 功能特性 | Claude Code | Cursor | 更优者 |
| ----------------- | ------------- | --------------- | ----------- |
| 自动任务执行 | ✅ 非常强 | ❌ 能力有限 | Claude Code |
| IDE 集成 | ❌ 仅命令行 | ✅ 原生 VS Code | Cursor |
| 实时代码补全 | ❌ 无 | ✅ 体验极佳 | Cursor |
| 多文件操作 | ✅ 非常强 | ⚠️ 还不错 | Claude Code |
| GitHub 一体化操作 | ✅ 可直接提交 | ⚠️ 需要手动操作 | Claude Code |
| 学习成本 | ⚠️ 中等 | ✅ 上手简单 | Cursor |
| 上下文长度 | ✅ 非常长 | ⚠️ 较好 | Claude Code |
| 调试辅助 | ✅ 自动化 | ⚠️ 较多需手动 | Claude Code |
表格来源：https://northflank.com/blog/claude-code-vs-cursor-comparison
@@ -152,7 +152,7 @@ Based on my environment variable settings:
setx ANTHROPIC_AUTH_TOKEN your_zai_api_key
setx ANTHROPIC_BASE_URL https://api.z.ai/api/anthropic
and my key(Replace it with your own key):
and my key(Replace it with your own key):
681fea485851d29060cc.13gfaendggaFOhb
please help me configure and start Claude Code
@@ -397,7 +397,7 @@ npm i -g @openai/codex
接下来，我们需要把获取到的 Key 填入下面的提示词中，并把整段提示词交给 Trae，让它帮你完成整个配置过程：
```Bash
````Bash
My API key is: [Paste your obtained sk-xxxxx key here]
Please help me complete the following configuration tasks:
@@ -440,7 +440,7 @@ Variable value: The key I gave you
The full path of the configuration file
Whether the environment variable was set successfully
I can use the command `codex --profile myrelay` to run it
```
````
配置完成后，你就可以通过 `codex --profile myrelay` 启动使用转发 API 的 Codex 了。之后的使用方式与 Claude Code 类似：只需要在对话框中随时输入你的想法和需求即可。