Init repo
This commit is contained in:
sanbuphy
@@ -0,0 +1,2 @@
|
||||
.DS_Store
|
||||
node_modules/*
|
||||
@@ -1,51 +1,158 @@
|
||||
# 项目名称
|
||||
<div align='center'>
|
||||
<img src="./assets/logo.png" alt="Vibe-Coding" width="20%">
|
||||
</div>
|
||||
<div align="center">
|
||||
<h1>Vibe-Coding</h1>
|
||||
<img src="https://img.shields.io/github/stars/datawhalechina/vibe-coding?style=flat&logo=github" alt="GitHub stars"/>
|
||||
<img src="https://img.shields.io/github/forks/datawhalechina/vibe-coding?style=flat&logo=github" alt="GitHub forks"/>
|
||||
<img src="https://img.shields.io/badge/language-Chinese-brightgreen?style=flat" alt="Language"/>
|
||||
<a href="https://github.com/datawhalechina/vibe-coding"><img src="https://img.shields.io/badge/GitHub-Project-blue?style=flat&logo=github" alt="GitHub Project"></a>
|
||||
</div>
|
||||
|
||||
*这里写项目的各类介绍信息、背景、动机等内容*
|
||||
<div align="center">
|
||||
|
||||
## 项目受众
|
||||
[中文](./README.md) | [English](./README.md)
|
||||
|
||||
*注：这里写你的项目所面向的受众，本项目能给他们带来什么，对他们的基础能力要求有哪些*
|
||||
</div>
|
||||
|
||||
## 目录
|
||||
*这里写你的项目目录，已完成的部分用添加上跳转链接*
|
||||
- [第1章](https://github.com/datawhalechina/repo-template/blob/main/docs/chapter1/chapter1.md)
|
||||
- [第2章](https://github.com/datawhalechina/repo-template/blob/main/docs/chapter2)
|
||||
- [2.1 我是2.1的标题](https://github.com/datawhalechina/repo-template/blob/main/docs/chapter2/chapter2_1.md)
|
||||
- [2.2 我是2.2的标题](https://github.com/datawhalechina/repo-template/blob/main/docs/chapter2/chapter2_2.md)
|
||||
- [第3章](https://github.com/datawhalechina/repo-template/blob/main/docs/chapter3)
|
||||
- [3.1 我是3.1的标题](https://github.com/datawhalechina/repo-template/blob/main/docs/chapter3/chapter3_1)
|
||||
- [3.1.1 我是3.1.1的标题](https://github.com/datawhalechina/repo-template/blob/main/docs/chapter3/chapter3_1/chapter3_1_1.md)
|
||||
- [3.1.2 我是3.1.2的标题](https://github.com/datawhalechina/repo-template/blob/main/docs/chapter3/chapter3_1/chapter3_1_2.md)
|
||||
- 3.2 我是3.2的标题
|
||||
- 第4章
|
||||
- 4.1 我是4.1的标题
|
||||
- 4.2 我是4.2的标题
|
||||
<div align="center">
|
||||
<h3>📚 Vibe Coding 原生 AI 应用实践教程</h3>
|
||||
<p>从零开始掌握 vibe coding，动手构建你的第一个 AI 原生应用</p>
|
||||
</div>
|
||||
|
||||
## 贡献者名单
|
||||
## 项目介绍
|
||||
|
||||
| 姓名 | 职责 | 简介 |
|
||||
| :----| :---- | :---- |
|
||||
| 小明 | 项目负责人 | 一个理想主义者 |
|
||||
| 小红 | 第1章贡献者 | 小明的朋友 |
|
||||
| 小强 | 第2章贡献者 | 小明的朋友 |
|
||||
> 这是一个面向所有想要学习 vibe coding 并构建原生 AI 应用的人的综合课程。本教程是 THU SIGS AIID 实践课程的一部分。受开源启发，所有资料向任何对 vibe coding 和原生 AI 应用感兴趣的人开放。我们希望这一资源能帮助每一个决心创造自己原生 AI 应用的人，并共同改变传统的编程习惯。我们相信未来的编程工作 95% 将由 AI 完成。
|
||||
|
||||
*注：表头可自定义，但必须在名单中标明项目负责人*
|
||||
本项目聚焦「原生 AI 应用开发」这一新范式，通过循序渐进的项目实战，帮助你在真实工程环境中掌握 vibe coding 的方法论与最佳实践。
|
||||
|
||||
### 项目受众
|
||||
|
||||
本项目主要面向希望系统学习 vibe coding 与原生 AI 应用开发的学习者，包括但不限于：
|
||||
|
||||
- 计算机科学、人工智能及相关或跨学科专业的学生，希望通过实践经验系统地介绍 vibe coding 和原生 AI 开发
|
||||
- 具有基本编程技能的初中级开发人员，希望学习 vibe coding 并构建原生 AI 应用程序
|
||||
- 开源爱好者和独立开发者，希望降低 AI 原生开发的门槛，并利用免费资源创建衍生作品
|
||||
- 旨在快速制作原生 AI 应用程序原型的企业技术团队和 AI 初创公司
|
||||
- 非开发人员角色（如产品经理），希望掌握基本开发任务并为 AI 计划提供技术支持
|
||||
|
||||
### 你将收获什么？
|
||||
|
||||
- 理解什么是 vibe coding 以及它与传统编程方式的差异
|
||||
- 掌握从零到一设计和实现原生 AI 应用的基本路径
|
||||
- 通过多个完整项目，熟悉游戏、工具类、产品原型等不同形态的 AI 应用开发
|
||||
- 了解并实践 Git、API、RAG、AI IDE、Zeabur 等关键工具与基础设施
|
||||
- 在实践中形成一套可复用的 AI 原生产品开发工作流
|
||||
|
||||
## 内容导航
|
||||
|
||||
### Project 部分
|
||||
|
||||
| 章节 | 关键内容 | 状态 |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---- |
|
||||
| [Project 1: 如何构建贪吃蛇游戏](https://github.com/datawhalechina/vibe-coding/blob/main/docs/project/chapter1/chapter1-how-to-build-a-snake-game.md) | 结合 AI 与代码实现经典贪吃蛇游戏 | ✅ |
|
||||
| [Project 2: 探索 AI 工具的能力边界](https://github.com/datawhalechina/vibe-coding/blob/main/docs/project/chapter2/chapter2-reach-the-capability-boundaries-of-ai-tools.md) | 系统体验与分析不同 AI 工具的能力边界 | ✅ |
|
||||
| [Project 3: Dify 入门与知识库集成](https://github.com/datawhalechina/vibe-coding/blob/main/docs/project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | 使用 Dify 搭建应用并完成知识库集成 | ✅ |
|
||||
| [Project 4: 一起做霍格沃茨画像](https://github.com/datawhalechina/vibe-coding/blob/main/docs/project/chapter4/chapter4-lets-build-hogwarts-portraits.md) | 基于多模态能力生成与迭代人物画像 | ✅ |
|
||||
| [Project 5: 从数据库到 Supabase](https://github.com/datawhalechina/vibe-coding/blob/main/docs/project/chapter5/chapter5-from-database-to-supabase.md) | 从传统数据库迁移到 Supabase 并完成应用接入 | ✅ |
|
||||
| [Project 6: 别急着写代码，先想一个好点子](https://github.com/datawhalechina/vibe-coding/blob/main/docs/project/chapter6/chapter6-no-code-without-an-idea.md) | 产品思维入门，从 0 构思并实现一个原生 AI 应用原型，涉及第一个应用 | ✅ |
|
||||
| Project 7: 构建第一个现代应用程序-UI设计 | 学会更高级的前端组件库的使用方式，前端编辑工具的深入用法，学习设计规范 | 🚧 |
|
||||
| Project 8: 构建第一个现代应用程序-功能设计 | 市场调研、学习产品 PRD 构建、深入理解产品原型设计、构架多页面产品原型和代码 | 🚧 |
|
||||
| Project 9: 构建第一个现代应用程序-全栈应用 | 构建与部署带鉴权与独立后端的应用、从参考到设计开发出可上线网页应用的完整闭环 | 🚧 |
|
||||
|
||||
### 扩展知识部分
|
||||
|
||||
| 章节 | 关键内容 | 状态 |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---- |
|
||||
| [扩展知识 1: 什么是 Git 和 GitHub](https://github.com/datawhalechina/vibe-coding/blob/main/docs/Extra/extra1/extra1-what-is-git-and-what-is-github.md) | 版本控制基础与 GitHub 使用入门 | ✅ |
|
||||
| [扩展知识 2: 什么是 API](https://github.com/datawhalechina/vibe-coding/blob/main/docs/Extra/extra2/extra2-what-is-api.md) | API 基本概念与在 AI 应用中的使用方式 | ✅ |
|
||||
| [扩展知识 3: AI 能力入门手册](https://github.com/datawhalechina/vibe-coding/blob/main/docs/Extra/extra3/extra3-ai-capability-starter-handbook.md) | 关于深度学习 AI 涉及到的所有主流模型与常见能力速览 | ✅ |
|
||||
| [扩展知识 4: 什么是 AI IDE 和 Trae](https://github.com/datawhalechina/vibe-coding/blob/main/docs/Extra/extra4/extra4-what-is-ai-ide-and-trae.md) | 了解 AI IDE 概念并上手 Trae 辅助开发 | ✅ |
|
||||
| [扩展知识 5: 什么是 RAG 以及它如何工作](https://github.com/datawhalechina/vibe-coding/blob/main/docs/Extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md) | RAG 原理、实现路径及未来演进方向 | ✅ |
|
||||
| [扩展知识 6: Zeabur 与 Web 应用部署](https://github.com/datawhalechina/vibe-coding/blob/main/docs/Extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | 使用 Zeabur 将 Web 与 AI 应用部署上线 | ✅ |
|
||||
| [扩展知识 7: CLI AI 编程工具与测试驱动开发原则](https://github.com/datawhalechina/vibe-coding/blob/main/docs/Extra/extra7/extra9-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | CLI AI 编程工具与测试驱动开发原则 | ✅ |
|
||||
| 扩展知识 8: MCP 与 ClaudeCode skills | MCP 与 ClaudeCode skills 的概念与方式深入解析 | 🚧 |
|
||||
| 扩展知识 9: 如何让 Coding Tools 长时间工作 | 如何通过配置让 ClaudeCode、Codex 等 CLI 工具连续工作数小时 | 🚧 |
|
||||
|
||||
### 实践项目部分
|
||||
|
||||
该部分将会覆盖常见电脑应用形式的 0-1 Vibe Coding 开发过程。
|
||||
|
||||
| 章节 | 关键内容 | 状态 |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---- |
|
||||
| [Example 1: 如何构建微信小程序](https://github.com/datawhalechina/vibe-coding/blob/main/docs/examples/example1/example1-how-to-build-a-wechat-miniprogram.md) | 使用 vibe coding 从 0 到 1 构建微信小程序 | ✅ |
|
||||
| Example 2: 如何构建微信小程序-包含后端 | 使用 vibe coding 从 0 到 1 构建具有后端数据库的微信小程序 | 🚧 |
|
||||
| Example 3: 如何构建安卓程序 | 结合 Expo，使用 vibe coding 从 0 到 1 构建安卓应用并上架 | 🚧 |
|
||||
|
||||
## 如何学习
|
||||
|
||||
- 建议具备基本编程经验（任意一门语言均可），并对 AI 与产品开发有兴趣
|
||||
- 按照 Project 模块从 0 到 6 依次实践，完成从小游戏到完整应用原型的进阶
|
||||
- 在 Extra 模块中补充 Git、API、RAG、部署等通识知识，完善你的 AI 开发知识图谱
|
||||
- 遇到问题时优先尝试自己排查与检索，再对照教程与源码进行比对和反思
|
||||
|
||||
你可以根据个人时间与需求，选择性地阅读和实践相关章节，但推荐至少完成全部 Project，以形成一套完整的实践闭环。
|
||||
|
||||
## 本地启动本课件
|
||||
|
||||
### 现代方案
|
||||
|
||||
在 AI IDE 对话框（vscode、cursor、trae 等）中，输入下列提示词启动本课件：
|
||||
|
||||
```
|
||||
请你帮我运行这个项目的本地服务
|
||||
```
|
||||
|
||||
### 旧方案
|
||||
|
||||
1. npm install
|
||||
2. npm run dev
|
||||
3. 打开浏览器访问 `http://localhost:3000` 即可查看。
|
||||
|
||||
## 参与贡献
|
||||
|
||||
- 如果你发现了一些问题，可以提Issue进行反馈，如果提完没有人回复你可以联系[保姆团队](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)的同学进行反馈跟进~
|
||||
- 如果你想参与贡献本项目，可以提Pull request，如果提完没有人回复你可以联系[保姆团队](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)的同学进行反馈跟进~
|
||||
- 如果你对 Datawhale 很感兴趣并想要发起一个新的项目，请按照[Datawhale开源项目指南](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)进行操作即可~
|
||||
- 如果你发现了一些问题，可以提 Issue 进行反馈，如果提完没有人回复你可以联系[保姆团队](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)的同学进行反馈跟进~
|
||||
- 如果你想参与贡献本项目，可以提 Pull Request，如果提完没有人回复你可以联系[保姆团队](https://github.com/datawhalechina/DOPMC/blob/main/OP.md)的同学进行反馈跟进~
|
||||
- 如果你对 Datawhale 很感兴趣并想要发起一个新的项目，请按照[Datawhale 开源项目指南](https://github.com/datawhalechina/DOPMC/blob/main/GUIDE.md)进行操作即可~
|
||||
|
||||
## 🙏 感谢每位贡献者
|
||||
|
||||
- [散步-项目负责人](https://github.com/sanbuphy) (Datawhale成员)
|
||||
- 方可-指导老师（Datawhale成员, 清华大学）
|
||||
- 赵芷霖（实践项目部分-清华大学）
|
||||
- [李亦萱](https://yixuan20.github.io/)（页面美术设计-清华大学）
|
||||
- AI Vibe Coding 101 内测群完整给建议体验的小伙伴们
|
||||
|
||||
### 特别感谢
|
||||
|
||||
- 感谢 [@Sm1les](https://github.com/Sm1les) 对本项目的帮助与支持
|
||||
- 感谢所有为本项目做出贡献的开发者们 ❤️
|
||||
|
||||
<div align=center style="margin-top: 30px;">
|
||||
<a href="https://github.com/datawhalechina/vibe-coding/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=datawhalechina/vibe-coding" />
|
||||
</a>
|
||||
</div>
|
||||
|
||||
## 关注我们
|
||||
|
||||
<div align=center>
|
||||
<p>扫描下方二维码关注公众号：Datawhale</p>
|
||||
<img src="https://raw.githubusercontent.com/datawhalechina/pumpkin-book/master/res/qrcode.jpeg" width = "180" height = "180">
|
||||
<img src="https://raw.githubusercontent.com/datawhalechina/pumpkin-book/master/res/qrcode.jpeg" width="180" height="180">
|
||||
</div>
|
||||
|
||||
## LICENSE
|
||||
|
||||
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="知识共享许可协议" style="border-width:0" src="https://img.shields.io/badge/license-CC%20BY--NC--SA%204.0-lightgrey" /></a><br />本作品采用<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议</a>进行许可。
|
||||
|
||||
*注：默认使用CC 4.0协议，也可根据自身项目情况选用其他协议*
|
||||
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">
|
||||
<img
|
||||
alt="知识共享许可协议"
|
||||
style="border-width:0"
|
||||
src="https://img.shields.io/badge/license-CC%20BY--NC--SA%204.0-lightgrey"
|
||||
/>
|
||||
</a>
|
||||
<br />
|
||||
本作品采用
|
||||
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">
|
||||
知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议
|
||||
</a>
|
||||
进行许可。
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 374 KiB |
@@ -1 +1,24 @@
|
||||
# Vibe Coding 101 课件
|
||||
|
||||
欢迎来到 Vibe Coding 101，你可以从左侧的 Project 和 Extra 模块进入具体内容。
|
||||
|
||||
## Project
|
||||
- [学习地图](project/chapter0-learning-map/chapter0-learning-map.md)
|
||||
- [Project 1: 如何构建贪吃蛇游戏](project/chapter1/chapter1-how-to-build-a-snake-game.md)
|
||||
- [Project 2: 探索 AI 工具的能力边界](project/chapter2/chapter2-reach-the-capability-boundaries-of-ai-tools.md)
|
||||
- [Project 3: Dify 入门与知识库集成](project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md)
|
||||
- [Project 4: 一起做霍格沃茨画像](project/chapter4/chapter4-lets-build-hogwarts-portraits.md)
|
||||
- [Project 5: 从数据库到 Supabase](project/chapter5/chapter5-from-database-to-supabase.md)
|
||||
- [Project 6: 没有 idea 就没有代码](project/chapter6/chapter6-no-code-without-an-idea.md)
|
||||
|
||||
## Extra
|
||||
- [扩展知识 1: 什么是 Git 和 GitHub](extra/extra1/extra1-what-is-git-and-what-is-github.md)
|
||||
- [扩展知识 2: 什么是 API](extra/extra2/extra2-what-is-api.md)
|
||||
- [扩展知识 3: AI 能力入门手册](extra/extra3/extra3-ai-capability-starter-handbook.md)
|
||||
- [扩展知识 4: 什么是 AI IDE 和 Trae](extra/extra4/extra4-what-is-ai-ide-and-trae.md)
|
||||
- [扩展知识 5: 什么是 RAG 以及它如何工作](extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md)
|
||||
- [扩展知识 6: Zeabur 与 Web 应用部署](extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md)
|
||||
- [扩展知识 9: CLI AI Coding 工具与 TDD 原则](extra/extra7/extra9-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md)
|
||||
|
||||
## Examples（完整实战项目）
|
||||
- [完整实战项目 1: 如何写一个微信小程序](examples/example1/example1-how-to-build-a-wechat-miniprogram.md)
|
||||
|
||||
+22
-8
@@ -1,8 +1,22 @@
|
||||
- 第1章 [我是第1章的标题](chapter1/chapter1)
|
||||
- 第2章 我是第2章的标题
|
||||
- [2.1 我是2.1的标题](chapter2/chapter2_1)
|
||||
- [2.2 我是2.2的标题](chapter2/chapter2_2)
|
||||
- 第3章 我是第3章的标题
|
||||
- 3.1 我是3.1的标题
|
||||
- 3.1.1 [我是3.1.1的标题](chapter3/chapter3_1/chapter3_1_1)
|
||||
- 3.1.2 [我是3.1.2的标题](chapter3/chapter3_1/chapter3_1_2)
|
||||
* [首页](/README.md)
|
||||
|
||||
* Project
|
||||
* [学习地图](/project/chapter0-learning-map/chapter0-learning-map.md)
|
||||
* [Project 1: 如何构建贪吃蛇游戏](/project/chapter1/chapter1-how-to-build-a-snake-game.md)
|
||||
* [Project 2: 探索 AI 工具的能力边界](/project/chapter2/chapter2-reach-the-capability-boundaries-of-ai-tools.md)
|
||||
* [Project 3: Dify 入门与知识库集成](/project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md)
|
||||
* [Project 4: 一起做霍格沃茨画像](/project/chapter4/chapter4-lets-build-hogwarts-portraits.md)
|
||||
* [Project 5: 从数据库到 Supabase](/project/chapter5/chapter5-from-database-to-supabase.md)
|
||||
* [Project 6: 没有 idea 就没有代码](/project/chapter6/chapter6-no-code-without-an-idea.md)
|
||||
|
||||
* Extra
|
||||
* [扩展知识 1: 什么是 Git 和 GitHub](/extra/extra1/extra1-what-is-git-and-what-is-github.md)
|
||||
* [扩展知识 2: 什么是 API](/extra/extra2/extra2-what-is-api.md)
|
||||
* [扩展知识 3: AI 能力入门手册](/extra/extra3/extra3-ai-capability-starter-handbook.md)
|
||||
* [扩展知识 4: 什么是 AI IDE 和 Trae](/extra/extra4/extra4-what-is-ai-ide-and-trae.md)
|
||||
* [扩展知识 5: 什么是 RAG 以及它如何工作](/extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md)
|
||||
* [扩展知识 6: Zeabur 与 Web 应用部署](/extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md)
|
||||
* [扩展知识 9: CLI AI Coding 工具与 TDD 原则](/extra/extra7/extra9-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md)
|
||||
|
||||
* Examples
|
||||
* [完整实战项目 1: 如何写一个微信小程序](/examples/example1/example1-how-to-build-a-wechat-miniprogram.md)
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
# 我是第1章的标题
|
||||
我是第1章的正文，下面给出插入图片的两种方式，分别为markdown语法和html语法。
|
||||
|
||||
markdown语法代码如下：
|
||||
```markdown
|
||||
|
||||
```
|
||||
效果如下：
|
||||
|
||||
|
||||
markdown语法简洁明了，但是其无法控制图片的大小，因此有图片缩放需求时可使用html语法，html语法代码如下：
|
||||
```html
|
||||
<div align=center>
|
||||
< img width="300" src="./images/1_1.jpeg"/>
|
||||
</div>
|
||||
<div align=center>图1.1 我是图片名称</div>
|
||||
```
|
||||
效果如下：
|
||||
<div align=center>
|
||||
<img width="300" src="./images/1_1.jpeg"/>
|
||||
</div>
|
||||
<div align=center>图1.1 我是图片名称</div>
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 67 KiB |
@@ -1 +0,0 @@
|
||||
111
|
||||
@@ -1,2 +0,0 @@
|
||||
# 我是2.1的标题
|
||||
我是2.1的正文
|
||||
@@ -1,2 +0,0 @@
|
||||
# 我是2.2的标题
|
||||
我是2.2的正文
|
||||
@@ -1,2 +0,0 @@
|
||||
# 我是3.1.1的标题
|
||||
我是3.1.1的正文
|
||||
@@ -1,2 +0,0 @@
|
||||
# 我是3.1.2的标题
|
||||
我是3.1.2的正文
|
||||
@@ -0,0 +1,447 @@
|
||||
# 如何构建一个最简单的微信小程序
|
||||
# 1. 什么是微信小程序和微信小程序开发
|
||||
|
||||
在这篇教程中，我们将完整跑通一条闭环：从脑海中的一个想法，到在微信里可以搜索、可以扫码打开的真实小程序。
|
||||
|
||||
开始动手之前，我们需要先建立两个基本认知。
|
||||
|
||||
第一个是 **本质**：微信小程序到底是什么？它和普通 App、网页有什么不同？为什么这么多产品会选择用小程序这种形态？只有理解了小程序的底层逻辑，你才能判断自己的想法是否适合用小程序来实现。
|
||||
|
||||
第二个是 **路径**：当你说「我要做一个小程序」时，从零到上线的完整路径是什么样的？这条路上有哪些关键节点——构思阶段要考虑什么、开发环境怎么搭建、如何用 AI 辅助开发提高效率、模拟器调试有哪些坑、测试号和正式发布各自解决什么问题。把整个流程在脑子里先跑一遍，后面实操时才不会迷路。
|
||||
|
||||
搞清楚这两个问题之后，我们就可以正式进入开发环节了。接下来，让我们先从第一个问题开始：微信小程序究竟是什么。
|
||||
|
||||
## 1.1 微信小程序
|
||||
|
||||
微信小程序可以看成藏在微信里的应用。它不需要你去应用商店搜索、下载、安装，只要在微信里搜名字、扫码，或者点开别人分享的卡片，就能马上使用。用完直接关掉，下次需要再打开即可，不会长期占据你的手机桌面和存储空间。
|
||||
|
||||
对普通用户来说，小程序解决的是很多「一件小事」：查快递、点咖啡、看订单、玩一局小游戏。打开速度快、入口统一在微信里，这是它最大的体验特征。
|
||||
|
||||
对企业和开发者来说，小程序是一种可以被搜索、被分享的「小应用形态」。只要在微信公众平台上注册、配置好信息，通过审核，小程序就能对所有微信用户开放。和传统 App 相比，它更容易获得第一批用户，因为大家已经习惯在微信里完成很多事情。
|
||||
|
||||
在本教程里，我们不会做复杂的业务系统，而是选一个很经典的例子——贪吃蛇小游戏。它体量小、逻辑清晰，却又包含了一个完整小程序需要具备的元素：多个页面、简单交互、状态变化、分数记录等，非常适合作为你的第一个作品。
|
||||
|
||||
## 1.2 微信小程序开发
|
||||
|
||||
理解了「小程序是什么」，接下来要回答的问题是：那开发一个小程序，到底要做什么？
|
||||
|
||||
你需要有一个清晰的目标（例如：做一个可以随时玩一局的贪吃蛇），设计出用户会看到的界面，告诉系统在不同操作下应该发生什么，并最终把这个作品发布出去。
|
||||
|
||||
在传统的开发流程里，上面这些步骤往往都由程序员主导，需要写大量代码。而在 AI 辅助开发的场景下，这件事可以拆得更细：你负责讲清楚想做什么，AI 帮你完成大部分具体怎么写。 这也意味着，对于刚入门的人来说，最重要的能力不再是背多少语法，而是能不能把需求描述清楚、能不能读懂 AI 给出的结果。
|
||||
|
||||
## 1.3 微信小程序开发的几种方法
|
||||
|
||||
真正做小程序时，大家采用的技术路线并不完全一样。为了避免你一上来就被各种名词淹没，我们只做一个粗略分类，让你知道常见的几条路分别长什么样。
|
||||
|
||||
第一种方式，是直接使用微信官方提供的原生能力。在微信开发者工具中创建项目后，你会看到一组固定的文件类型，用它们来描述页面结构、样式和逻辑。这种方式贴近官方文档，控制力强，但对第一次接触前端的人来说，学习曲线会稍微曲折一些。
|
||||
|
||||
第二种方式，是利用多端框架，比如 uni-app 等。你在本地主要是写类似网页的代码（例如 .vue 文件），然后通过框架把这套代码转换成微信小程序可以识别的形式。这样的好处是：结构更统一，以后如果想把产品发布到其他平台（比如 H5、App），改动会相对少一些。
|
||||
|
||||
基于以上两种方式，本教程会重点讲述使用 AI 辅助开发工具的小程序开发SOP。比如把整个项目在 Trae 里打开，然后直接对内置的 AI 助手说： 请帮我在这个文件里加一个首页，有标题和按钮——请帮我写一个游戏页面，可以显示贪吃蛇和分数，AI 会在理解现有代码的基础上，为你生成新的代码片段，或者帮你修改、重构。
|
||||
|
||||
这三种方式并不是互斥的。你完全可以在一个 uni-app 项目里，借助 Trae 的 AI 功能来完成大部分编码工作。关键不是选哪一个方法，而是知道：自己现在处在什么位置，以及有哪些工具可以用。
|
||||
|
||||
## 1.4 本文介绍的微信小程序开发步骤（粗略预览）
|
||||
|
||||
本教程会带着**从环境到成品**的节奏，专门围绕贪吃蛇这个例子，结合 Trae 的 vibecoding 方式，把整个过程拆成一条你可以反复复用的路线。整体上，你将在后面的章节里经历这样几个阶段：
|
||||
|
||||
1. 先搭建认知地基：弄清楚什么是微信小程序、常见的开发方式有哪些，以及我们要做的这款贪吃蛇小程序面向谁、在什么场景被使用。
|
||||
2. 然后完成环境准备：注册小程序账号，安装 HBuilderX、Trae 和微信开发者工具，并用 HBuilderX 创建一个可以在微信开发者工具中跑起来的基础项目骨架，让屏幕上先出现一个最简单的页面。
|
||||
3. 接下来进入正式开发：在 Trae 中打开这个项目，用 vibecoding 的方式和 AI 对话，一步步生成首页和游戏页的布局，实现蛇移动、吃食物、游戏结束等核心玩法。
|
||||
4. 在功能跑通之后，学会把 AI 当成「调试和重构伙伴」：遇到 bug 时请它一起排查，觉得结构乱时让它帮忙整理，并逐渐加上开始 / 暂停、最高分记录、界面微调等细节体验。
|
||||
5. 最后进入发布环节：把项目构建成微信可识别的版本，在微信开发者工具中做预览和真机测试，先以测试号和体验版的形式上线验证流程，完成备案和审核后，再把小程序正式发布出去，让别人也能在微信里搜索到、玩到你的作品。
|
||||
|
||||
这一节只负责把全景图画出来，不展开具体命令和代码。你现在需要做的只是先大致记住这 5 步： **理解 → 搭环境 → vibecoding 开发 → 调试打磨 → 构建发布** 。后面的章节会在每一步上慢慢放大，告诉你要准备什么、要和 AI 说什么，以及在每个阶段你应该在屏幕上看到怎样的结果。
|
||||
|
||||
# 2. 环境准备
|
||||
|
||||
在开始写任何一行代码之前，我们先把开发环境准备好。 这一部分的目标，是让你在后面的章节里不再纠结 **去哪儿下载软件、为什么运行不了** ，而是可以直接把注意力放在和 AI 对话、实现需求上。
|
||||
|
||||
你只需要会打开浏览器、下载文件、双击安装程序，就可以完成本节全部步骤。
|
||||
|
||||
## 2.1 本教程会用到的三个工具
|
||||
|
||||
整个贪吃蛇小程序的开发，我们会同时用到三个工具，它们各自负责不同的环节：
|
||||
|
||||
1. 第一个是 Trae。你可以把它理解为一款集成了 AI 的代码编辑器，既能像普通 IDE 一样打开项目文件，又能让你直接用自然语言和 AI 交流，请它帮你写代码、改代码、解释代码。本教程里，大部分「和 AI 一起写小程序」的操作，都会在 Trae 里完成。你可以在浏览器中访问 https://www.trae.cn 获取最新版本。
|
||||
2. 第二个是 HBuilderX。它是一款对 Vue 和 uni-app 支持特别好的编辑器，官方提供了很多现成的小程序项目模板。我们会用它来「一键生成」一个基础的小程序项目，相当于先打好地基，再把地基交给 Trae 和 AI 去改造。HBuilderX 的下载地址是 https://www.dcloud.io/hbuilderx.html 。
|
||||
3. 第三个是微信开发者工具。这是微信官方提供的专门用来开发和预览小程序的工具。它负责把你写好的项目在电脑上跑起来，并支持在手机上进行真机调试。你可以从 https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html 下载适合你操作系统的版本。
|
||||
|
||||
简单总结一下：HBuilderX 帮你快速建一个小程序项目，Trae 帮你和 AI 一起写代码，微信开发者工具帮你看到真正运行中的小程序。
|
||||
|
||||
## 2.2 注册微信公众平台账号并获取 AppID
|
||||
|
||||
有了工具，还需要一个 **小程序身份** ，这一步在微信公众平台上完成。 如果你之前从来没有注册过微信小程序，可以按照下面的顺序来做：
|
||||
|
||||
1. 在浏览器地址栏输入 https://mp.weixin.qq.com ，打开微信公众平台网页，用你的微信扫码登录。
|
||||
|
||||
|
||||
|
||||
2. 在首页选择「小程序」，按照页面提示完成注册流程，填写邮箱、手机号以及主体类型（个人或企业）。
|
||||
|
||||
3. 注册成功并进入后台后，找到「开发管理」或「开发设置」页面，就能看到一个唯一的编号，名字叫 AppID 。这个编号后面会用在项目配置里，相当于你这个小程序在微信里的身份证。
|
||||
|
||||
|
||||
|
||||
建议你把 AppID 记录在一个方便找到的地方。后续章节在配置项目时，我们会直接把这个值填进去，让本地项目和线上小程序对应起来。
|
||||
|
||||
## 2.3 安装微信开发者工具
|
||||
|
||||
接下来，我们需要一个地方实际运行和预览小程序，这就是微信开发者工具存在的意义。
|
||||
|
||||
1. 访问下载页面 https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html 。 在这个页面上，你会看到针对不同操作系统的多个版本，通常选择与你电脑系统匹配的稳定版即可，比如 Windows 64 位或 macOS 版本。
|
||||
2. 下载完成后，双击安装包，按照安装向导一步步点击下一步。如果你不清楚要改什么设置，保持默认选项就可以。
|
||||
3. 安装结束后，从桌面或开始菜单启动微信开发者工具。首次启动时，它会在屏幕上显示一个二维码，提示你用手机微信扫码登录。用自己的微信扫码并确认授权后，就可以进入主界面。
|
||||
|
||||
|
||||
|
||||
后面当我们在 Trae 中准备好项目文件之后，就会把构建好的小程序导入到微信开发者工具里，在这里看到真实的运行效果。
|
||||
|
||||
## 2.4 准备 Trae 和 HBuilderX
|
||||
|
||||
最后，我们把真正负责写项目的两个工具安装好：Trae 和 HBuilderX。
|
||||
|
||||
你可以 **先安装 Trae** 。打开浏览器访问 https://www.trae.cn ，根据页面提示下载适合你系统的版本。安装过程和普通软件一样，双击安装包，按提示完成即可。安装完成后，你会得到一个可以打开本地文件夹、查看代码、和 AI 对话的 IDE，后续所有 vibecoding 步骤都会在这里进行。
|
||||
|
||||
|
||||
|
||||
**接着安装 HBuilderX** 。访问 https://www.dcloud.io/hbuilderx.html ，选择对应操作系统的发行包下载。HBuilderX 的包体非常小，启动速度也很快。安装完成后，你可以先熟悉一下它的界面，不需要深入研究功能；在后面的章节中，我们会用它来创建一个 uni-app 小程序模板，作为整个项目的起点。
|
||||
|
||||
|
||||
|
||||
完成本节的所有步骤之后，你已经具备了完整的开发环境：有微信小程序的账号和 AppID，有可以预览的小程序运行环境，也有可以和 AI 一起写代码的 IDE。在接下来的部分，我们会从**创建第一个小程序项目骨架**开始，让这些工具真正跑起来。
|
||||
|
||||
## 2.5基础文件准备
|
||||
|
||||
1. 点击新建项目
|
||||
|
||||
|
||||
|
||||
2. 选择默认模板，给小程序起名，选择存放路径，带你及右下角的创建：
|
||||
|
||||
|
||||
|
||||
3. 显示创建成功！
|
||||
|
||||
|
||||
|
||||
4. 接着可以在对应的文件夹中找到该文件夹，在Trae里面打开该文件夹，可以看到地基文件已经全部建造好：
|
||||
|
||||
|
||||
|
||||
# 3. 小程序开发
|
||||
|
||||
前面两部分，我们已经搞清楚了「小程序是什么」、以及「环境怎么配、工具怎么装」。 从这一节开始，正式进入实战：不再停留在概念层面，而是让 AI 真正帮你把贪吃蛇小程序从无到有做出来。
|
||||
|
||||
这一节，你会完整走完一次「开发环节」的 SOP，大致包括几步：
|
||||
|
||||
1. 在 Trae 里把当前项目打开，给 AI 下第一条完整指令，让它基于现有骨架设计并实现一个可运行的贪吃蛇版本。
|
||||
2. 让 Trae 直接改动真实项目文件，而不是只给你“示例代码”，并学会用回退功能在需要时恢复到修改前的状态。
|
||||
3. 回到 HBuilderX 和微信开发者工具，通过「运行到小程序模拟器」的方式在模拟器里试玩这一版，实现从“代码视角”到“用户视角”的切换。
|
||||
4. 根据试玩结果，用自然语言持续提出修改需求，让 AI 帮你从按键控制迭代到摇杆控制，顺便体验一次「发现问题 → 描述问题 → AI 修复 → 再次验证」的闭环。
|
||||
|
||||
你当然可以选择先在开发前，把每个页面、每个按钮都想得一清二楚，再交给 AI。 但对完全小白来说，小程序的界面和交互设计本身也是一个全新的领域（后面我们会教你怎么用 AI 帮忙做设计），所以在这一次，我们刻意采用另一种方式： 先开干 ——让 AI 先生成一个能跑起来的版本，再一边看效果、一边用自然语言慢慢打磨和调整。
|
||||
|
||||
## 3.1 把需求一次性说清楚：给 Trae 下第一条“总指令”
|
||||
|
||||
打开 Trae，载入前面已经准备好的小程序项目之后，我先没有急着改某一行代码，而是对内置的 AI 助手说了这样一件事：
|
||||
|
||||
**我向AI“发号施令”，说我现在需要基于现在的框架写一个贪吃蛇小程序，请给设计此小程序并我写一个prompt。**
|
||||
|
||||
也就是说，我不是「一点点要求它写某个函数」，而是先抛出一个完整目标，让 AI 帮我规划，但是AI不仅帮我做了计划，还直接落地第一版实现。
|
||||
|
||||
Trae 收到这条指令之后，会自动阅读当前项目结构，判断应该在哪些文件里增加页面、在哪些地方补充逻辑，然后直接对项目中的文件或代码做出修改，而不需要你自己去手搓代码或者增删改查文件/文件夹。
|
||||
|
||||
## 3.2 让 AI 自动修改代码，而不是“手搓”
|
||||
|
||||
当你在 Trae 中点击执行这条指令时，AI 会进入一个「帮你改工程」的流程。 在这个过程中，你可以看到几个关键点：
|
||||
|
||||
1. 它会在对话区解释自己的思路，比如会在哪个目录下新增页面、打算如何组织游戏逻辑。
|
||||
|
||||
|
||||
|
||||
2. 它会直接对真实项目文件做增删改，而不是只给你一段「示例代码」让你自己拷贝。
|
||||
3. 修改完成后，Trae 会生成一个简短的小结，告诉你：这次它改了哪些文件，大致做了哪些事情。
|
||||
|
||||
如果你对这一轮修改不满意（或者觉得某一步有问题），也不用紧张。Trae 在你发出对话的对话框外的左上角提供了「回退」能力，你可以一键把工程恢复到本次指令执行之前的状态，相当于给这次操作加了一个安全的撤销键。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 3.3 在 HBuilderX 和微信开发者工具中查看效果
|
||||
|
||||
AI 完成第一轮开发之后，代码已经落在项目里了，但这时候你还没有看到玩家视角的效果。 下一步，我们需要把它跑起来。
|
||||
|
||||
具体做法是：回到 HBuilderX，找到顶部菜单的「运行」选项，选择「运行到小程序模拟器」中的「微信开发者工具」。这一操作会触发项目编译，并将结果交给微信开发者工具打开。
|
||||
|
||||
|
||||
|
||||
底部的输出窗口会显示编译的过程。如果最终状态是「ready」且没有报错，就说明构建成功，你可以切到微信开发者工具里查看这一版小程序的界面和功能。
|
||||
|
||||
|
||||
|
||||
在大多数情况下，HBuilderX 会自动帮你打开微信开发者工具，让你直接看到新的小程序。如果没有自动打开，你可以按下面的方式处理：
|
||||
|
||||
1. 先在 HBuilderX 中停止当前运行。
|
||||
2. 手动启动微信开发者工具，让它处于打开状态。
|
||||
3. 回到 HBuilderX，再次点击「运行 → 运行到小程序模拟器 → 微信开发者工具」。
|
||||
|
||||
这样我们就可以微信小程序开发者工具中看到我们Vibecoding的小程序：
|
||||
|
||||
|
||||
|
||||
## 3.4 用自然语言反复调整和完善小程序，直到我们满意
|
||||
|
||||
在这次实践中，AI 一开始给我生成的是按键控制方向的贪吃蛇：屏幕上有四个方向按钮，点击不同方向，蛇就会改变运动方向。 功能上完全可以玩，但我个人更喜欢用摇杆控制。对于你的调整需求（不仅限于功能、UI设计、界面，等你熟练后，你甚至可以用自然语言让AI帮你接入其他大模型的API或接入数据库）——再强调一遍，你只需要用自然语言告诉大模型即可。
|
||||
|
||||
这就是 vibecoding 的优势所在：你不必自己去翻代码，查找事件绑定的位置、计算坐标的逻辑，而是直接把想法告诉 AI。例如，你可以在 Trae 的对话框里这样描述：
|
||||
|
||||
把按键换成摇杆控制，并且用户松开摇杆时蛇保持同方向移动，直到用户再次松开摇杆。
|
||||
|
||||
只要你把需求讲得足够清楚，AI 会自动定位到对应界面和逻辑文件，替你完成控件样式、交互绑定和方向处理等改动。
|
||||
|
||||
|
||||
|
||||
修改完成后，再回到微信开发者工具中查看。 如果没有立刻看到变化，可以尝试点击开发者工具上的「运行」按钮，或者刷新小程序预览窗口，让最新的构建结果生效。 仍然没有更新时，可以在 HBuilderX 中先停止运行，再重新执行一次「运行到小程序模拟器」，即可看到调整之后的小程序：
|
||||
|
||||
|
||||
|
||||
## 3.5 出现问题怎么办：继续用自然语言沟通
|
||||
|
||||
AI 生成的版本不一定一开始就完美。有时候你会遇到这些情况：
|
||||
|
||||
* 运行时报错，小程序无法正常打开；
|
||||
* 功能大致正确，但细节和你想象的不太一样；
|
||||
* 界面可以用，但你觉得还可以更好看或更顺手。
|
||||
|
||||
在这些时候，不需要自己钻进代码里盲改，而是可以把遇到的问题直接用自然语言重新描述给 Trae 中的 AI 助手，例如：
|
||||
|
||||
现在摇杆控制已经生效了，但有时候蛇会突然停止不动，请帮我检查当前实现哪里有问题。 或者： 现在游戏可以玩，但界面有点拥挤，我希望在手机上显示时上下留出更多空白。请你帮我调整布局。
|
||||
|
||||
AI 会根据你当前的项目状态和描述，给出修改建议并直接应用在代码里。如果修改之后结果更糟或方向不对，你依然可以使用回退，把工程恢复到前一个稳定版本，再换一种说法尝试。
|
||||
|
||||
通过这几轮往返，你会从最初的“毛坯版本”，逐步打磨出一个更贴近自己喜好的摇杆版贪吃蛇小程序。例如我给出了一种图画风格，让AI根据此风格来调整小程序的UI风格：
|
||||
|
||||
|
||||
|
||||
## 3.6 最终成品与本节小结
|
||||
|
||||
经过一轮又一轮的 **自然语言叙述 → AI 修改 → 在微信开发者工具中预览 → 继续对话微调** ，我最终得到的是这样一个成品：
|
||||
|
||||
* 有完整的游戏页面；
|
||||
* 蛇可以顺畅移动并吃到食物；
|
||||
* 支持摇杆控制；
|
||||
* 在小程序模拟器中可以顺利运行。
|
||||
|
||||
最终开发成品如下：
|
||||
|
||||
|
||||
|
||||
在这一节里，你已经看到了一个完整的闭环：
|
||||
|
||||
1. 在 Trae 中用一句清晰的指令，让 AI 搭出第一版贪吃蛇小程序；
|
||||
2. 借助 HBuilderX 和微信开发者工具，从用户视角检查实际效果；
|
||||
3. 用自然语言反复向 AI 提出修改需求，让它替你完成功能调整和界面优化；
|
||||
4. 在任何一步出现问题时，都可以通过回退和重新运行来保证安全。
|
||||
|
||||
接下来，你可以按照同样的节奏去尝试自己的想法：不一定非要是贪吃蛇，也可以是一个工具小程序、一个活动页，甚至是你工作中真正需要的业务原型。你的主要任务，是把需求想清楚、说清楚，其余的交给 AI 和这些工具来配合完成。
|
||||
|
||||
# 4.小程序发布
|
||||
|
||||
前面三章，我们已经完成了从 **搭环境** ——**和 AI 一起开发**到**在本地模拟器里跑通贪吃蛇**的整个流程。
|
||||
|
||||
从这一章开始，我们关心的问题变成了：**怎样把这个作品真正挂到微信上，不只是一个小玩具，而是所有人都可以使用的微信小程序呢？**
|
||||
|
||||
为了降低门槛，我们先走一条 **最短闭环** ：只让它以**测试号**的形式上线，先自己和少数同学体验；等到你觉得功能和体验都足够稳定，再走正式上线流程。
|
||||
|
||||
本章先讲到 4.1，帮你完成**测试号上线**这条最短路径；关于面向所有用户的正式上线，会在 4.2 中再展开。
|
||||
|
||||
## 4.1 最短 SOP —— 测试号上线
|
||||
|
||||
这一小节的目标只有一个：让你在微信里，真的能以**体验版**的形式打开自己的贪吃蛇小程序。
|
||||
|
||||
整个流程可以理解为四件事：
|
||||
|
||||
1. 在微信公众平台找到并确认自己的 AppID。
|
||||
2. 在项目里把这个 AppID 配置好。
|
||||
3. 用微信开发者工具上传当前版本。
|
||||
4. 回到公众平台，把这次上传的版本设置为「体验版」。
|
||||
|
||||
下面我们按照这个顺序来走一遍。
|
||||
|
||||
### 4.1.1 在微信公众平台确认 AppID
|
||||
|
||||
第一步，是在微信公众平台上确认你的小程序 AppID。
|
||||
|
||||
这一步你之前在**2.环境准备**时已经做过一次，这里是把它真正用起来。
|
||||
|
||||
1. 打开浏览器，访问 `https://mp.weixin.qq.com`，登录你的小程序后台。
|
||||
2. 在左侧菜单中找到「开发管理」，进入其中的「开发设置」。
|
||||
3. 在页面上方，你会看到一块叫做「开发者 ID」的区域，里面有一行「AppID（小程序 ID）」——这就是你的小程序唯一编号。
|
||||
|
||||
这串编号需要和项目中的配置一一对应，否则微信会认为你上传的是「别人的小程序」，自然无法正常预览和发布。
|
||||
|
||||
|
||||
|
||||
### 4.1.2 在项目中填写 AppID
|
||||
|
||||
第二步是把这个 AppID 写进你的项目配置里，让本地构建出来的小程序和公众平台上的这个「账号」对应上。
|
||||
|
||||
如果你是用 uni-app 模板来做的项目，可以按照下面的方式操作：
|
||||
|
||||
1. 打开 HBuilderX，载入你的贪吃蛇项目。
|
||||
2. 在左侧文件树中找到 `manifest.json`，双击打开。
|
||||
3. 下拉到「微信小程序配置」这一栏，你会看到一个输入框，提示类似「微信小程序 AppID（请在微信开发者工具中获取）」。
|
||||
4. 把刚才在公众平台上看到的 AppID 原样粘贴进来，保存文件。
|
||||
|
||||
|
||||
到这里为止，你的本地项目就已经认领了这个小程序身份。接下来，只要通过微信开发者工具上传版本，它就会被记在这个 AppID 名下。
|
||||
|
||||
### 4.1.3 在微信开发者工具中上传一个版本
|
||||
|
||||
前面我们已经用 HBuilderX 把项目运行到微信开发者工具里，看过模拟器中的效果。
|
||||
|
||||
现在要做的是：在开发者工具中，把当前这份代码“”打一个版本包”上传到服务器上。
|
||||
|
||||
大致步骤如下：
|
||||
|
||||
1. 在微信开发者工具顶部工具栏的右侧，你会看到一个「上传」按钮，点击它。
|
||||
2. 弹出的窗口中，需要填写两个关键字段：
|
||||
1. 版本号：例如 `1.0.0`，只允许数字和小数点。
|
||||
2. 项目备注：写一段简短说明，比如「完成基本功能的开发」。
|
||||
3. 检查无误后，点击「上传」按钮。下面的输出区域会显示编译过程，所有步骤变成绿色并提示上传完成，就说明这一版已经成功提交到了微信服务器。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### 4.1.4 在管理后台中把版本设为体验版
|
||||
|
||||
上传只是把代码送到了微信这边，还没告诉系统“这是一版可以试用的体验版本”。
|
||||
|
||||
最后一步，我们回到公众平台的小程序后台，完成这个闭环。
|
||||
|
||||
1. 再次打开 `https://mp.weixin.qq.com`，进入你的小程序后台。
|
||||
2. 在左侧找到「管理」下面的「版本管理」，点击进入。
|
||||
3. 在页面的「开发版本」一栏，你应该能看到刚刚上传的那个版本：版本号是 `1.0.0`，备注是你写的那一段说明，时间是刚刚的上传时间。
|
||||
4. 在这一行的右侧，会有一个下拉按钮或操作按钮，可以选择「设为体验版」，点击之后，确认操作，注意在这一步之前请确保你已经在首页-小程序类目设置好了你的主营类目。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
完成之后，这个版本就变成了你的小程序「体验版」。你可以在后台生成体验版二维码，也可以把自己和同事加入「体验成员」，让大家用微信扫描后，在真机上体验这款贪吃蛇小程序。
|
||||
|
||||
到这里，我们就完成了从本地项目到测试号上线的最短闭环：
|
||||
|
||||
你不需要一开始就面向所有微信用户开放，只是在一个安全的范围内，让真实的小程序跑在真实的微信环境里。这足够你用来测试功能、收集反馈、继续迭代。
|
||||
|
||||
## 4.2 小程序正式上线
|
||||
|
||||
体验版跑通之后，你已经可以在自己的微信里玩到这款贪吃蛇小程序了。 接下来要做的，就是把它从只有少数体验成员能用的状态，推进到全民可用正式微信小程序。
|
||||
|
||||
把这件事拆成几步：先补充信息，再选择类目，然后完成备案，最后提交审核。下面按照这个顺序走一遍。
|
||||
|
||||
### 4.2.1 进入小程序发布流程
|
||||
|
||||
首先回到微信公众平台后台，登录你的小程序账号。 在左侧导航里找到与「版本管理 / 发布」相关的入口（不同时间界面可能略有调整），展开后会看到「小程序发布流程」这一项。
|
||||
|
||||
点击进入之后，界面上方会显示一个进度条，下面依次列出几个步骤，例如：
|
||||
|
||||
1. 小程序信息
|
||||
2. 小程序类目
|
||||
3. 运营信息 / 小程序备案
|
||||
4. 微信认证（视你的主体而定）
|
||||
|
||||
一开始进度会显示 0%，随着你完成每一步，系统会自动把进度向前推进。
|
||||
|
||||
|
||||
|
||||
### 4.2.2 填写小程序基本信息
|
||||
|
||||
第一步是把小程序的「名片」补充完整，这也是用户在微信里第一次看到你的时候会接触到的内容。
|
||||
|
||||
在「小程序信息」页面，你通常需要填写和确认以下内容：
|
||||
|
||||
1. 小程序名称 这个名字会出现在搜索结果和小程序顶部，有长度限制，同时需要符合微信的命名规范。建议选择既能表达功能，又方便记忆的名称，例如「贪吃蛇 vibecoding 版」这一类。
|
||||
2. 功能介绍 / 简介 用一两句话说明这个小程序是做什么的，例如：「一款用 AI 辅助开发完成的贪吃蛇小游戏，适合在碎片时间玩一局。」 注意简介要和实际功能一致，避免使用夸张宣传语。
|
||||
3. 图标和展示图片
|
||||
1. 图标一般要求为正方形图片，支持 PNG/JPG 等格式，大小和像素有明确限制（以页面说明为准），建议提供一张简洁、对比度高的图。
|
||||
2. 展示图片可以上传几张小程序页面的截图，例如首页、游戏页面、设置界面等，这些会出现在详情页中，帮助用户了解内容。
|
||||
4. 其他必要信息 例如标签、服务区域等，根据页面提示填写即可。 原则只有一个：所有填写的内容都要和这款贪吃蛇小程序真实功能相符。
|
||||
|
||||
|
||||
|
||||
全部填写完毕后，点击保存或下一步，发布流程中的第一步就完成了。
|
||||
|
||||
### 4.2.3 选择小程序服务类目
|
||||
|
||||
完成基本信息后，向导会引导你进入「小程序类目」步骤。 类目可以理解为小程序在微信里的「归属分类」，决定它在审核时会被归入哪一类应用，也会影响后续展示和运营。
|
||||
|
||||
|
||||
|
||||
在这个页面，你会看到「添加类目」按钮。点击后，可以从系统提供的分类树中选择适合你小程序的方向，例如：
|
||||
|
||||
|
||||
|
||||
1. 先选择「教育」这一大类；
|
||||
2. 再在下面选择「教育工具 / 教学辅助」等更具体的子类，本次我选择了教育器具，当做大家学习Vibecoding的教具吧~
|
||||
|
||||
你在自己的项目里，只需要根据实际用途选择最贴切的一项即可。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
确认类目后，点击保存。如果页面提示「创建类目成功」，并在列表中显示你刚刚添加的那一项，就说明这一步已经完成。
|
||||
|
||||
### 4.2.4 完成小程序备案信息
|
||||
|
||||
接下来，发布流程会要求你完成「运营信息 / 小程序备案」部分。这一步是为了验证小程序的主体身份，确保上线的应用有明确责任人。
|
||||
|
||||
|
||||
|
||||
在个人主体的示例下，大致会经历这样几个动作：
|
||||
|
||||
1. 选择备案类型 页面会让你在不同主体类型之间进行选择，例如「个人」「企业」等。根据你注册小程序时的主体保持一致即可。
|
||||
2. 填写主体信息 包括姓名、证件类型、证件号码等基本信息。 这一部分需要与注册信息保持一致，否则可能会在审核时被退回。
|
||||
3. 上传证明材料 页面通常会要求你上传身份证照片或其他证明文件，具体格式、清晰度和大小要求会写在说明里。 按提示准备好图片后上传，确保内容清晰可辨。
|
||||
|
||||
|
||||
提交之后，系统会进入「审核中」状态，页面上会显示类似「信息已提交，请耐心等待」的提示。这个过程可能需要一定时间，你可以在后台随时查看备案进度。
|
||||
|
||||
|
||||
|
||||
### 4.2.5 提交审核并等待正式发布
|
||||
|
||||
当「小程序信息」「小程序类目」「运营信息 / 备案」等步骤全部被勾选完成后，你就可以进行最后一个动作：提交审核。
|
||||
|
||||
1. 回到「小程序发布流程」总览页面，确认每一项都显示为已完成，进度条接近 100%。
|
||||
2. 根据页面提示，点击「提交审核」或类似按钮，把当前开发版本送交微信团队审核。
|
||||
3. 在「版本管理」中，你会看到这次提交的版本状态变为「审核中」。通过后，会变成「已发布」或可选择「上线」的状态。
|
||||
|
||||
备案审核不通过会打电话给开发者，提示不通过的部分。
|
||||
|
||||
备案会收到“工业和信息化部”发来的验证码，和核验链接，点击进入把验证码和个人信息填入就行（核验有效期是1天）备案通过会收到“工业和信息化部”发送的邮件和短信通知，并且告知备案号。微信认证：个人缴纳30元，公司企业貌似是300元，不管认证是否通过都钱都不退回，会收到认证通知，并且接到电话确认信息
|
||||
|
||||
提交进行审核，要上传操作视频和页面，填好信息提交即可 ，点击“提交发布”，就正式发布了
|
||||
|
||||
|
||||
|
||||
# 5.总结
|
||||
|
||||
到这里，你已经完整跑完了一次**从0到1**的小程序开发闭环： 从认识微信小程序，到装好 Trae、HBuilderX 和微信开发者工具；从把想法丢给 AI，让它在代码里替你“搬砖”，到在模拟器里试玩第一版贪吃蛇；再到把作品打成体验版、走完备案和审核，真正在微信里让人使用——这条链路你已经亲手走通了一遍。
|
||||
|
||||
更重要的是，你不是靠死记硬背语法做到这一点的，而是靠清楚地表达需求 + 和 AI 有效沟通来实现的 。你已经体验过 **:一句自然语言指令，可以让AI完美满足你的开发要求** 。这种能力不会只停留在贪吃蛇上，它可以迁移到你以后想做的任何小程序——工具、活动页、教学应用，甚至是你工作中的真实项目。
|
||||
|
||||
如果要给你一个 **通用SOP** ，其实只有五步：** 想清楚一个小需求 → 在 Trae 里搭好项目骨架 → 用 vibecoding 和 AI 搭出第一版 → 在微信开发者工具里不断试玩和改进 → 上传、备案、审核、上线。** 每次你重复这五步，就会多一个真正能被人打开、能被分享的小程序，也会多一份「我可以用 AI 把点子变成产品」的信心。
|
||||
|
||||
接下来，你可以继续打磨这款贪吃蛇，也可以关掉它，重新起一个空项目，从你自己的想法出发。无论做什么，只要记住一点： 你不再只是一个「想做点东西」的人，而是已经跑通了全流程的 vibecoding 开发者。剩下的，就是多做几次，把这种能力变成习惯。
|
||||
|
||||
# 参考资料：
|
||||
|
||||
- https://zhuanlan.zhihu.com/p/1889401120939567074
|
||||
- https://blog.csdn.net/2401_87407347/article/details/155193007
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 553 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 235 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 113 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 85 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 144 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 71 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 64 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 92 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 81 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 104 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 124 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 104 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 104 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 106 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 55 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 120 KiB |
@@ -0,0 +1,279 @@
|
||||
# 扩展知识 1 - 什么是 Git 和 GitHub
|
||||
|
||||
在之前的课程中，我们学习了如何使用基于 Web 的 vibe coding 工具编写代码。每次对话都会创建一个新版本的代码。但是，让我们思考一个问题：如果我们想恢复到之前的修改，有没有方便的方法？有没有一种工具可以记录我们在不同阶段的代码，使我们能够随时在不同版本之间切换和修改？
|
||||
|
||||
为了满足这一需求，版本控制软件应运而生。在这篇文章中，我们将介绍最著名的版本控制程序——Git——以及最好的代码托管平台——GitHub。我们将学习如何使用 Git 进行代码管理，如何从 GitHub 获取他人的代码，如何上传我们自己的代码，以及如何与他人合作进行大型项目。
|
||||
|
||||
无论是个人项目的版本跟踪，团队协作中的代码同步，还是为开源社区做贡献，Git 和 GitHub 都是现代开发者的必备工具。通过掌握它们，你将能够更高效地管理代码，根据需要创建检查点，在代码的不同阶段之间自由切换，并轻松处理从单个文件更改到开发大型项目的所有事务——使每一次代码迭代都可控且可追溯。
|
||||
|
||||
# 什么是 Git
|
||||
|
||||
Git 是由 Linux 内核开发者 Linus Torvalds 于 2005 年创建的分布式版本控制系统。其核心功能是跟踪文件的修改历史，允许开发者随时查看和回滚到以前的版本，并在与他人协作时高效地合并更改。
|
||||
|
||||
|
||||
|
||||
与早期的集中式版本控制系统相比，Git 的“分布式”特性允许每个开发者的本地设备存储代码仓库的完整历史记录。大多数操作（如提交、回滚和分支管理）都可以在不依赖中央服务器的情况下执行，这使得 Git 更灵活，更适合大规模协作和离线工作。
|
||||
|
||||
> 💡 在操作 Git 之前，让我们先了解一下什么是终端。
|
||||
>
|
||||
> ## 什么是终端？
|
||||
>
|
||||
> 终端本质上是一个基于文本的“计算机接入点”。在早期，图形界面（没有图标，没有鼠标点击）出现之前，用户只能通过键入文本命令与计算机交互。这种方法代代相传，成为了我们要介绍的今天的终端。
|
||||
>
|
||||
> 它不依赖花哨的界面，纯粹通过“命令 + 反馈”工作。这使其成为人机交互最基本和直接的方法之一。
|
||||
>
|
||||
> 不同系统的终端有所不同。在 Windows 上，常见的是“命令提示符 (cmd)”和“PowerShell”。你可以通过在计算机的运行/搜索框中输入“cmd”或“powershell”来启动这些命令行程序。
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 前者是一个较旧的工具，仅支持基本命令，如查看文件和复制，适合简单任务。后者是一个更高级的版本，可以处理复杂的操作，如进程管理和远程控制，并且还兼容 cmd 命令——使其在开发或系统管理场景中更常用。macOS 和 Linux 都默认带有“终端”，它们的命令逻辑相似，源自 Unix（贝尔实验室工程师在 20 世纪 60 年代末开发的经典计算机系统）。
|
||||
>
|
||||
> 终端在今天仍然至关重要，因为它的效率和广泛的兼容性。例如，一条命令可以批量重命名文件，比用鼠标重复点击快得多。此外，本地服务器、云服务器和专业开发环境通常没有图形界面，因此终端操作是必要的。许多任务，如安装各种程序（如 Git、Python、系统工具或开发依赖项）、运行代码、管理计算机进程和配置系统参数，也需要终端命令。
|
||||
>
|
||||
> 你可能会想，如果记不住所有那些终端命令该怎么办。事实上，随着大语言模型的快速发展，不再需要像以前那样死记硬背了。现在，你只需要在需要时询问模型（例如“如何用 Git 获取远程代码？”或“如何通过命令行删除文件夹或批量创建文件夹？”），然后从回复中复制有用的命令即可。
|
||||
>
|
||||
> 
|
||||
|
||||
## 如何安装 Git
|
||||
|
||||
我们将演示在不同计算机操作系统上安装 Git 的三种方法。请根据你的系统版本按照说明进行操作：
|
||||
|
||||
### Windows
|
||||
|
||||
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. 双击安装程序并按照安装向导说明进行操作：
|
||||
|
||||
|
||||
1. 建议保持默认选项。如果你需要自定义，请注意以下几点：（在大多数情况下，你可以一直点击“Next”）
|
||||
* 选择 Git 使用的默认编辑器：选择你喜欢的编辑器（如 VS Code）。你可以默认选择第一个选项，即 Vim（一个文本编辑器），或选择“Visual Studio Code as Git's default editor”选项（需要预先安装 VS Code）。你可以保持默认选择并点击“Next”继续。
|
||||
|
||||
* 选择如何使用 Git：这三个选项控制 Git 在系统中的可访问性。建议选择选项 2（“from command line and 3rd-party software”）——它将基本的 Git 工具添加到 PATH 中，让你可以在 Git Bash、命令提示符、PowerShell 和 IDE 中使用 Git，而不会使系统混乱。
|
||||
|
||||
3. 安装后，在桌面上右键单击。如果在菜单中看到“Git Bash Here”，则安装成功。
|
||||
|
||||
|
||||
|
||||
### MacOS
|
||||
|
||||
对于 macOS，你可以首先在终端中输入 `git --version` 来检查是否已经安装了 Git。如果没有，系统会提示你安装——只需按照说明完成安装即可。
|
||||
|
||||
1. 方法 1：通过 Homebrew 安装
|
||||
如果你安装了 [Homebrew](https://brew.sh/)（Mac 包管理器），请打开终端并输入
|
||||
```Bash
|
||||
brew install git
|
||||
```
|
||||
2. 方法 2：（推荐）通过 Xcode 安装： https://developer.apple.com/xcode/ ，Xcode 内置了 Git。安装后，只需按照说明继续操作。
|
||||
|
||||
### Linux
|
||||
|
||||
大多数 Linux 发行版可以通过其包管理器安装 Git：
|
||||
|
||||
* Ubuntu/Debian:
|
||||
|
||||
```Bash
|
||||
sudo apt update
|
||||
sudo apt install git
|
||||
```
|
||||
|
||||
* CentOS/RHEL:
|
||||
|
||||
```Bash
|
||||
sudo yum install git
|
||||
```
|
||||
|
||||
* 验证安装：在终端中输入 git --version。如果显示版本号，则安装成功。
|
||||
|
||||
## Git 初始化
|
||||
|
||||
安装 Git 后，你首先需要配置你的用户信息——这是使用 Git 进行版本控制的基本步骤。在终端中执行以下命令（将括号中的内容替换为你自己的信息）：
|
||||
|
||||
```Bash
|
||||
# 设置全局用户名（将显示在提交记录中）
|
||||
git config --global user.name "Your Name"
|
||||
|
||||
# 设置全局邮箱（建议使用在 GitHub/GitLab 等平台上注册的邮箱）
|
||||
git config --global user.email "your.email@example.com"
|
||||
```
|
||||
|
||||
Git 会将此信息嵌入到每个提交记录中，作为每次修改的“作者信息”。查看版本历史记录（例如，使用 git log）时，你可以清楚地看到谁修改了每一行代码，便于追溯责任和沟通。在协作项目中，统一的身份信息使团队成员能够快速识别谁做了哪些更改，从而提高协作效率（例如通过提交记录找到相关开发人员讨论问题）。
|
||||
|
||||
你可以通过在命令行中输入 `git config --list` 来查看当前的 Git 配置信息，以确认设置成功。
|
||||
|
||||
# 什么是 GitHub
|
||||
|
||||
GitHub 是一个基于 Git 的代码托管平台。它不仅为 Git 仓库提供远程存储，还包括协作工具（如 Issues、Pull Requests、Projects），使开发者更容易分享代码和协作。简而言之，Git 是一个本地版本控制工具，而 GitHub 是一个远程“代码仓库云盘 + 协作社区”。
|
||||
|
||||
GitHub 不仅是世界上最大的代码托管平台，也是全球最活跃、最具影响力的开源社区。这里“开源”的核心思想是任何人都可以下载并运行软件的源代码。这种模式允许世界各地的人们检查彼此的代码并进行修改，或基于此创建新项目。例如，你可以在 GitHub 上找到各种学习教程以及用于训练 GPT 模型的框架（如 PyTorch）的完整源代码。每天，无数人在全球范围内协作审查和改进代码。
|
||||
|
||||
|
||||
|
||||
许多大公司在 GitHub 上开源他们的程序或教程，以获得行业竞争优势——这也可以看作是一种广告形式。在 GitHub 社区中，项目获得的“星标 (stars)”数量是衡量其价值的主要指标；项目或组织拥有的星标越多，其可信度和影响力就越大。
|
||||
|
||||
|
||||
|
||||
在我们的课程中，支持资源和作业也将上传到专用的 GitHub 仓库。通过上传作业的过程，你将逐渐熟悉并掌握 GitHub 的使用，为未来应用程序开发中的版本控制打下坚实的基础。
|
||||
|
||||
## 注册 GitHub 账号
|
||||
|
||||
1. 访问 [GitHub 官网](https://github.com/) 并点击右上角的“Sign up”。
|
||||
|
||||
2. 输入你的电子邮件地址（建议使用常用邮箱，因为验证和通知将发送到那里），设置密码（必须包含字母、数字和特殊字符）。
|
||||
3. 完成人工验证，按照提示验证邮箱，你的账号就创建好了。
|
||||
|
||||
## 在 GitHub 上创建你的第一个仓库
|
||||
|
||||
接下来，我们将创建第一个存储文件夹，也称为仓库或“repo”。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
1. Repository name：向他人显示的仓库名称。
|
||||
2. Description：仓库的详细描述。
|
||||
3. Choose visibility：对于个人仓库，如果设置为 private，只有你和特别邀请的人可以看到。如果设置为 public，所有人都可以看到。
|
||||
对于组织内的仓库，如果是 Private，只有组织内的人可以看到。
|
||||
如果是 Public，组织外的人也可以看到。
|
||||
4. README：通常的惯例是每个仓库都应该有一个 README 文件。你可以把它看作是仓库的完整介绍，包括使用说明、文件列表和操作方法。
|
||||
5. Add .gitignore and license：
|
||||
1. .gitignore 文件告诉 Git 在上传到 GitHub 时忽略某些文件夹或文件，因此它们不会被跟踪或添加到暂存区。这对于临时测试文件、依赖包或大文件很有用。一旦指定，这些文件将不再被跟踪。
|
||||
2. license 指的是你选择的开源许可证类型。不同的许可证详细规定了他人是否可以将你的代码用于商业目的，并包含其他条款和条件。
|
||||
|
||||
建议勾选“Add README”，将仓库可见性设置为“Private”，并根据自己的喜好填写仓库名称和描述，然后点击“Create repository”完成创建第一个远程仓库。
|
||||
|
||||
|
||||
|
||||
之后，你将拥有一个没有任何额外文件的干净仓库。接下来你可以开始上传文件了。
|
||||
|
||||
|
||||
|
||||
获取仓库的命令是 `git clone`，但它需要仓库地址。你可以通过点击绿色的“Code”按钮找到仓库地址，你会看到 HTTPS 和 SSH 选项。通常，你可以使用这两种方法中的任何一种将仓库下载到本地机器（只有这样你才能修改和上传文件）。
|
||||
|
||||
|
||||
|
||||
一般来说，通过 HTTP 克隆的仓库适合临时下载和测试他人的仓库，但不建议用于自己的开发。为了更好的学习体验，你应该先设置 SSH 认证。
|
||||
|
||||
## 绑定本地 SSH
|
||||
|
||||
在 GitHub 中，“SSH 协议绑定”本质上意味着将你本地设备的 SSH 公钥与你的 GitHub 账号关联，允许 GitHub 通过 SSH 协议识别你的设备。这使你能够安全地操作远程仓库，而无需密码（如 clone、push 或 pull 代码）。
|
||||
|
||||
简单来说：这就像给你的设备一张“GitHub 专属门禁卡”。绑定后，当你的设备通过 SSH 协议访问 GitHub 仓库时，GitHub 会验证这张“门禁卡”（你的 SSH 公钥）。一旦确认为你的授权设备，你就可以直接操作——不需要每次都输入账号密码。
|
||||
|
||||
> 💡 什么是 SSH
|
||||
|
||||
### 为什么需要 SSH 协议绑定？
|
||||
|
||||
GitHub 支持两种主要的仓库操作协议：HTTPS 协议和 SSH 协议：
|
||||
|
||||
* HTTPS 协议：每次操作（如 push）都需要输入 GitHub 账号密码（或个人访问令牌 PAT）。验证过程繁琐，且存在密码泄露风险。
|
||||
* SSH 协议：身份验证通过“密钥对”完成，因此不需要重复输入密码，且加密传输更加安全。
|
||||
|
||||
“SSH 协议绑定”是启用 GitHub SSH 认证的前提步骤——只有将本地 SSH 公钥“绑定”到 GitHub 账号后，GitHub 才能识别你的设备并允许对仓库进行 SSH 操作。
|
||||
|
||||
### “绑定”的核心逻辑：SSH 密钥对的作用
|
||||
|
||||
SSH 认证依赖于密钥对（公钥 + 私钥），它们是匹配的加密文件。生成后，你需要将“公钥”提供给 GitHub（“绑定”），而“私钥”留在本地设备上：
|
||||
|
||||
1. 私钥：存储在本地设备（如电脑）的指定目录中（通常是 ~/.ssh/），充当“你的专属钥匙”，绝不能与任何人分享。
|
||||
2. 公钥：这是一把可以公开分享的“锁”——你需要将其复制到 GitHub 账号的“SSH keys list”中（“绑定”操作）。
|
||||
|
||||
当你通过 SSH 操作 GitHub 仓库时（例如 git push git@github.com:xxx/xxx.git）：
|
||||
|
||||
* 你的本地设备使用私钥加密“操作请求”并发送给 GitHub；
|
||||
* 收到请求后，GitHub 尝试使用你之前绑定的公钥进行解密；
|
||||
* 如果解密成功，你的设备被确认为已授权，操作被允许；否则，访问被拒绝。
|
||||
|
||||
### “绑定”的具体步骤（核心流程）
|
||||
|
||||
一旦你理解了原理，实际操作就很简单——核心是“生成密钥对 → 上传公钥到 GitHub”：
|
||||
|
||||
1. 本地生成 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`
|
||||
|
||||
|
||||
|
||||
输入提示词后，你还需要在左侧终端按 Enter 键，否则命令会一直等待而不执行。由于 Trae 无法帮你执行任何条件判断，我们只需要一直按 Enter 即可。
|
||||
|
||||
最后，你会看到右侧的 Trae 返回了它读取的公钥。你只需复制它并准备在下一步中粘贴。
|
||||
|
||||
|
||||
2. 手动获取公钥
|
||||
打开你的本地终端（在 Windows 上使用 Git Bash 或 PowerShell；在 macOS/Linux 上使用终端），输入以下命令（将 your_email@example.com 替换为你注册 GitHub 账号时使用的邮箱）：
|
||||
|
||||
```Bash
|
||||
ssh-keygen -t ed25519 -C "your_email@example.com"
|
||||
```
|
||||
|
||||
1. 按 Enter 接受默认值（默认文件路径，无密码，或根据需要设置密码）。这将在 ~/.ssh/ 目录中生成两个文件：
|
||||
* id_ed25519：私钥（本地保存，**绝不分享**）；
|
||||
* id_ed25519.pub：公钥（需要上传到 GitHub）。
|
||||
2. 将公钥“绑定”到你的 GitHub 账号
|
||||
|
||||
这是核心绑定步骤——将本地公钥添加到 GitHub 账号的“SSH keys list”中：
|
||||
|
||||
1. 复制公钥内容：
|
||||
1. Trae：
|
||||
2. Windows：用记事本打开 C:\Users\<your>\.ssh\id_ed25519.pub 并复制其所有内容；
|
||||
3. macOS/Linux：在终端运行 cat ~/.ssh/id_ed25519.pub 并复制所有输出（从开头的 SSH-ed25519 到结尾的邮箱）。
|
||||
2. 登录 GitHub 并进入“SSH Key Management”页面：
|
||||
1. 点击右上角头像 → Settings → 左侧菜单 SSH and GPG keys → 点击 New SSH key。
|
||||
|
||||
2. 输入任何标题（例如，your local computer's SSH），然后将你刚刚获取的 SSH 公钥粘贴到这里。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
3. 验证绑定是否成功
|
||||
|
||||
在终端中输入以下命令（**Trae 也可以做以下操作**）来测试 GitHub 是否能识别你的设备：
|
||||
|
||||
```Bash
|
||||
ssh -T git@github.com
|
||||
```
|
||||
|
||||
* 如果你看到类似 Hi [your GitHub username]! You've successfully authenticated... 的内容，说明你已成功绑定密钥；
|
||||
* 如果遇到错误，通常是因为公钥复制不完整、私钥权限过高（你的本地 ~/.ssh/ 目录应仅由你读写）等。根据需要检查这些问题。
|
||||
|
||||
### 重要注意事项
|
||||
|
||||
如果你有多个设备（如笔记本电脑和台式机），你需要为每个设备生成单独的 SSH 密钥对，并将每个公钥绑定到同一个 GitHub 账号——每个设备都有自己的“门禁卡”。
|
||||
|
||||
切勿分享你的私钥（不要上传到 GitHub 或与他人分享），否则有人可能会冒充你操作你的仓库。如果私钥泄露，请立即从 GitHub 删除相应的公钥并生成新的密钥对。
|
||||
|
||||
绑定 SSH 后，使用 SSH 格式的仓库地址（例如 git@github.com:username/repository.git）进行操作，而不是 HTTPS 格式（例如 https://github.com/username/repository.git）。如果你之前用 HTTPS 克隆了仓库，可以用 git remote set-url origin `<new>` 切换协议。
|
||||
|
||||
# 使用 Trae 进行 GitHub 操作
|
||||
|
||||
我们已经解释了什么是 Git，什么是 GitHub，什么是 SSH，以及如何配置它。现在你可以自由使用 Trae 执行 Git 操作。首先，让我们学习如何将远程仓库克隆到本地机器。
|
||||
|
||||
## Git clone : 下载现有仓库
|
||||
|
||||
你可以直接告诉它你想克隆的仓库地址
|
||||
|
||||
|
||||
|
||||
## Git pull : 从远程仓库获取更新
|
||||
|
||||
每次更新仓库之前，由于它可能由多人维护，你需要先拉取最新的更改。之后，你可以修改并推送文件。
|
||||
|
||||
**记得包含文件夹名称及其相对或绝对路径，以避免推送到错误的仓库。**
|
||||
|
||||
prompt:`Help me pull this repository AIID-TEST in ./AIID-TEST.`
|
||||
|
||||
## Git commit & Git push : 暂存更新并推送到 GitHub
|
||||
|
||||
一切准备就绪后，你可以尝试修改本地文件，在文件夹中添加或删除项目。然后，让 Trae 检测更改并帮你推送到 GitHub。
|
||||
|
||||
prompt:`I finished. Commit and push to the repository AIID-TEST in ./AIID-TEST.`
|
||||
|
||||
|
||||
|
||||
推送成功。现在你可以在 GitHub 上看到更新的内容了。
|
||||
|
||||
# 参考资料
|
||||
|
||||
* Pro Git book https://git-scm.com/book/en/v2
|
||||
* GitHub Docs https://docs.github.com/en
|
||||
@@ -0,0 +1,258 @@
|
||||
# 扩展知识 2 - 什么是 API
|
||||
|
||||
在本教程中，我们将学习什么是 API，它是如何工作的，并了解它是如何驱动我们每天使用的数字体验的。
|
||||
|
||||
# 你将学到
|
||||
|
||||
* 使用简单、真实的类比来理解什么是 API。
|
||||
* API 请求和响应循环的基本步骤。
|
||||
* 如何识别你日常使用的应用中的 API，如天气、地图和社交媒体。
|
||||
* 为什么 API 对于现代技术的创新、安全和效率至关重要。
|
||||
|
||||
# **什么是 API？ - 自动售货机类比**
|
||||
|
||||
想象一下你想从自动售货机买一罐汽水。
|
||||
|
||||
1. **你不需要知道它内部是如何工作的：** 你不关心冷却系统、机械臂，或者它是如何验证你的钱的。对你来说，它是一个“黑盒子”。
|
||||
2. **它有清晰的操作按钮：** 机器上有一排排按钮，每个按钮都清楚地标明了它提供的饮料。这是你与它交流的唯一方式。你必须按下“汽水”按钮。
|
||||
3. **简单的“请求”和“响应”：**
|
||||
1. 你投入硬币并按下“汽水”按钮。这是你的 **“请求”**。
|
||||
2. 机器发出嗡嗡声，一罐汽水掉了下来供你拿取。这是它的 **“响应”**。
|
||||
|
||||
在这个例子中：
|
||||
|
||||
* 你是你的程序（比如一个移动应用）。
|
||||
* 自动售货机是另一个程序或服务（比如天气服务或地图服务）。
|
||||
* 机器上的按钮就是 API。
|
||||
|
||||
API，全称 Application Programming Interface（应用程序编程接口），就是那组“按钮”。它是不同软件组件之间进行通信的一种预定义的、直接的方式，允许一个程序轻松地从另一个程序获取它需要的东西（数据或功能），而无需了解其内部的复杂性。
|
||||
|
||||
API 连接了各种软件系统，为开发者和用户带来了巨大的好处。
|
||||
|
||||
* **创新：** 公共 API 允许任何开发者使用强大的功能（如支付处理或地图）来创建新的数字体验，而无需从头开始构建它们。
|
||||
* **自动化：** API 可以自动化重复性工作，如发送电子邮件或在系统之间共享数据，提高生产力，让人类可以专注于更有创造性的任务。
|
||||
* **安全性：** API 充当安全的守门人。它们可以要求对任何请求进行身份验证，增加一层保护，防止未经授权访问敏感数据。
|
||||
* **成本效率：** 企业可以使用第三方 API 来访问有用的工具和基础设施，帮助他们避免构建复杂内部系统的巨额费用。
|
||||
|
||||
API 是现代数字世界的基石。通过理解请求和响应这个简单的概念，你已经迈出了进入更广阔、互联的软件开发世界的第一步。
|
||||
|
||||
# API 是如何工作的？
|
||||
|
||||
API 通过 **请求和响应** 循环在应用程序之间共享数据。让我们把它想象成在餐厅点餐。
|
||||
|
||||
在这个比喻中，你是 **API 客户端**（发出请求的应用程序），服务员是 **API**，厨房是 **API 服务器**（拥有数据或功能的系统）。
|
||||
|
||||
## **API 请求（你的订单）**
|
||||
|
||||
客户端通过向服务器发送请求来开始对话。这就像告诉服务员你想要什么。一个典型的 API 请求包括：
|
||||
|
||||
* **Endpoint（端点）：** 指向资源的特定 URL。这就像菜单上的特定项目。对于天气应用，端点可能是 `/current-weather`。
|
||||
* **Method（方法）：** 你想执行的操作。最常见的是 `GET`，意味着你想获取数据。其他的包括 `POST`（创建新数据）、`PUT`（更新数据）和 `DELETE`（删除数据）。
|
||||
* **Parameters（参数）：** 指定请求的额外细节。如果你询问天气，你需要提供位置。例如：`city=London`。
|
||||
* **Request Body（请求体）：** 创建或更新资源所需的实际数据。如果你要向社交媒体应用发布新照片，照片本身就在请求体中。
|
||||
|
||||
## **API 响应（你的食物到了）**
|
||||
|
||||
在厨房（服务器）准备好你的订单后，服务员（API）将其带回给你。响应包括：
|
||||
|
||||
* **Status Code（状态码）：** 一个三位数的代码，指示结果。`200 OK` 表示请求成功。`404 Not Found` 表示找不到请求的资源。
|
||||
* **Response Body（响应体）：** 你请求的实际数据或内容。对于天气请求，这将是包含温度、状况和湿度的结构化数据。
|
||||
|
||||
# 现实世界的例子：我们周围的 API
|
||||
|
||||
API 无处不在，在后台默默工作。让我们看几个常见的“自动售货机”。
|
||||
|
||||
### **天气预报 API**
|
||||
|
||||
这个 API 就像一个只卖天气信息的自动售货机。
|
||||
|
||||
* **它提供什么：** 当前天气、未来几天的预报、空气质量等。
|
||||
* **一个简单的‘请求’示例：**
|
||||
* **Endpoint:** `/current-weather`
|
||||
* **Parameters:** `city=London` & `apiKey=your_access_key`（证明你有权限）
|
||||
|
||||
‘响应’（它返回的数据）：
|
||||
|
||||
```JSON
|
||||
{
|
||||
"city": "London",
|
||||
"temperature": "15°C",
|
||||
"condition": "Cloudy",
|
||||
"humidity": "70%"
|
||||
}
|
||||
```
|
||||
|
||||
* 你的天气应用获取这些数据并以用户友好的格式显示。
|
||||
|
||||
### **地图服务 API（如 Google Maps）**
|
||||
|
||||
这个自动售货机专门提供地理信息。
|
||||
|
||||
* **它提供什么：** 行车路线、从地址查找坐标、搜索附近地点。
|
||||
* **一个简单的‘请求’示例：**
|
||||
* **Endpoint:** `/directions`
|
||||
* **Parameters:** `origin=Eiffel Tower` & `destination=Louvre Museum` & `mode=driving`
|
||||
|
||||
```JSON
|
||||
{
|
||||
"total_distance": "4.5 kilometers",
|
||||
"estimated_time": "15 minutes",
|
||||
"route_steps": [
|
||||
"1. Head east on Champ de Mars...",
|
||||
"2. Turn left onto Quai Branly...",
|
||||
"..."
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
* 拼车或送货应用使用这些数据在地图上绘制路线并提供逐向导航指令。
|
||||
|
||||
### **社交媒体登录 API（如“使用 Google 登录”）**
|
||||
|
||||
这是一个特殊的自动售货机，不卖产品；它帮助“验证你的身份”。
|
||||
|
||||
* **它提供什么：**
|
||||
|
||||
确认用户身份并安全地向另一个应用提供基本信息（如姓名和头像）。
|
||||
|
||||
* **它是如何工作的：**
|
||||
* 你在新的购物应用上点击“使用 Google 登录”。
|
||||
* 购物应用向 Google 的 API 发出请求：“嘿，有个用户想登录。你能确认他是谁吗？”
|
||||
* Google 请求你的批准。
|
||||
* 一旦你批准，Google 的 API 向购物应用发送响应：“身份已确认。用户是‘John Doe’。”
|
||||
这样，购物应用就知道你是谁，而无需看到你的密码，既方便又安全。
|
||||
|
||||
### **大语言模型 API（如 OpenAI 或 DeepSeek）**
|
||||
|
||||
这是一个 **“超级大脑”自动售货机**。你给它一个纯文本的命令或问题，它给你一个详细的、类似人类的文本回复。
|
||||
|
||||
* **它提供什么：** 为几乎任何任务生成原创文本，如回答问题、写邮件、总结文章或创建计算机代码。
|
||||
* **它是如何工作的：**
|
||||
* 想象你正在使用一个新的“AI 写作助手”应用程序。你输入一个命令：“给我的团队写一封简短、专业的邮件，关于新项目的截止日期。”
|
||||
* 写作应用向 OpenAI 的 API 发出请求：“嘿，有个用户想写封邮件。你能生成关于新项目截止日期的专业信息的文本吗？”
|
||||
* OpenAI API 处理此命令，理解上下文和语气，并生成文本。
|
||||
* API 向写作应用发送响应：“请求完成。这是邮件文本：‘Hi Team, This is a quick update to let you know that the deadline for Project X has been moved to this Friday...’”
|
||||
|
||||
通过这种方式，写作应用可以即时为用户提供强大的 AI 功能，而无需从头开始构建自己的大型语言模型。
|
||||
|
||||
# 在 Z.ai 上查看 LLM API
|
||||
|
||||
接下来，我们将学习调用大语言模型 API 的基本方法。我们可以简单参考之前贪吃蛇游戏的 API 使用示例。
|
||||
|
||||
我们不需要自己搜索。我们需要做的就是向语言模型提出后续问题，例如：“在代码中，哪几行调用了语言模型和图像生成模型？”，“如果用 Python 代码写会是什么样？”通过问这些问题，你将能直接得到完整的答案。
|
||||
|
||||
|
||||
|
||||
这些 API 是使用官方智谱 SDK（SDK 代表 **软件开发工具包**）调用的。接下来，让我们看看如何调用 OpenAI 的官方 API。
|
||||
|
||||
你稍后可能会遇到很多名词。不需要一下子掌握所有名词——**你只需要在这里大致了解它们的样子**。
|
||||
|
||||
### Python API
|
||||
|
||||
要在 Python 中调用 OpenAI 的文本生成 API，可以使用官方的 openai 库。
|
||||
|
||||
**`base_url`** 参数指定 API 的端点。默认情况下，它指向 OpenAI 的服务器（例如 `https://api.openai.com/v1/`）。如果你使用代理、自托管服务器或兼容的提供商，你可能需要将此参数更改为相应的地址。
|
||||
|
||||
```Python
|
||||
import openai
|
||||
|
||||
openai.api_key = "YOUR_OPENAI_API_KEY"
|
||||
# 如果你使用自定义 base URL（例如 Azure、代理或其他提供商）
|
||||
# openai.base_url = "<https://your-custom-base-url/v1/>"
|
||||
|
||||
response = openai.ChatCompletion.create(
|
||||
model="gpt-3.5-turbo",
|
||||
messages=[
|
||||
{"role": "system", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "Hello, how can I use the OpenAI API?"}
|
||||
]
|
||||
)
|
||||
|
||||
print(response.choices[0].message["content"])
|
||||
```
|
||||
|
||||
**注意：**
|
||||
|
||||
* `openai.api_key` 是你的秘密 API 密钥。
|
||||
* `openai.base_url` 是可选的，仅当你未使默认 OpenAI 端点时才需要。
|
||||
* `model` 参数指定你想使用的语言模型。
|
||||
|
||||
许多其他流行的大语言模型都兼容 OpenAI API 调用格式。例如，如果你需要使用 [DeepSeek](https://platform.deepseek.com/sign_in)（中国最好的大语言模型之一），你可以通过更改 API 端点和模型名称以非常相似的方式进行操作。
|
||||
|
||||
以下是典型示例：
|
||||
|
||||
```JavaScript
|
||||
import openai
|
||||
|
||||
openai.api_key = "YOUR_DEEPSEEK_API_KEY"
|
||||
openai.base_url = "<https://api.deepseek.com/v1/>" # DeepSeek 的端点
|
||||
|
||||
response = openai.ChatCompletion.create(
|
||||
model="deepseek-chat", # 更改为 DeepSeek 的模型名称
|
||||
messages=[
|
||||
{"role": "system", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "Tell me about DeepSeek."}
|
||||
]
|
||||
)
|
||||
|
||||
print(response.choices[0].message["content"])
|
||||
```
|
||||
|
||||
### 前端 API
|
||||
|
||||
如果你想从 React 前端调用 OpenAI API，绝不应该直接在浏览器中暴露你的 API 密钥。
|
||||
|
||||
相反，使用 **后端代理**（例如 Express.js），或从服务器函数安全地调用 API。
|
||||
|
||||
```JavaScript
|
||||
// 安装命令：npm install express axios dotenv
|
||||
const express = require("express");
|
||||
const axios = require("axios");
|
||||
require("dotenv").config();
|
||||
|
||||
const app = express();
|
||||
app.use(express.json());
|
||||
|
||||
app.post("/api/chat", async (req, res) => {
|
||||
try {
|
||||
const userMessage = req.body.message;
|
||||
|
||||
const response = await axios.post(
|
||||
"<https://api.openai.com/v1/chat/completions>",
|
||||
{
|
||||
model: "gpt-3.5-turbo",
|
||||
messages: [
|
||||
{ role: "system", content: "You are a helpful assistant." },
|
||||
{ role: "user", content: userMessage }
|
||||
]
|
||||
},
|
||||
{
|
||||
headers: {
|
||||
"Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
|
||||
"Content-Type": "application/json"
|
||||
}
|
||||
}
|
||||
);
|
||||
|
||||
res.json({ reply: response.data.choices[0].message.content });
|
||||
} catch (error) {
|
||||
res.status(500).json({ error: error.message });
|
||||
}
|
||||
});
|
||||
|
||||
app.listen(3001, () => {
|
||||
console.log("Server listening on port 3001");
|
||||
});`
|
||||
```
|
||||
|
||||
要测试这个 Node.js 程序，首先使用 npm install express axios dotenv 安装所需的包，并将你的 OpenAI API 密钥保存在 .env 文件中，格式为 `OPENAI_API_KEY=your_key_here`。然后，使用 node server.js 运行服务器。一旦运行起来，你可以通过使用工具如 curl 或 Postman 发送带有 JSON 体（如 `{"message": "Hello"}`）的 POST 请求到 [http://localhost:3001/api/chat](http://localhost:3001/api/chat) 来测试 /api/chat 端点，你应该会收到来自 OpenAI API 的回复。
|
||||
|
||||
```JavaScript
|
||||
curl -X POST <http://localhost:3001/api/chat> \\
|
||||
-H "Content-Type: application/json" \\
|
||||
-d '{"message":"Hello, who are you?"}'
|
||||
```
|
||||
|
||||
# 参考资料
|
||||
|
||||
* https://www.postman.com/what-is-an-api/
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,169 @@
|
||||
# 扩展知识 4 - 什么是 AI IDE 和 Trae
|
||||
|
||||
在之前的学习阶段，我们使用 z.ai 搭建了最简单的 Web 程序和网页小游戏。但如果我们想要构建更复杂的应用——比如功能更完善的网站、桌面程序，甚至是手机应用——就必须在自己的电脑上使用专业的编程软件来编写代码。
|
||||
|
||||
最早的时候，只需要在一个简单的文本文件里写好程序，再用专门的语言处理器去读取并打包执行就够了。但随着代码量越来越大、项目结构越来越复杂，人工管理大量文件、手动编辑庞大的项目变得越来越困难。开发者因此迫切需要一种工具，能够高效管理和切换大量代码文件，支持多种编程语言的语法高亮，并可以快速定位和调试问题。于是，集成开发环境（IDE，Integrated Development Environment）就应运而生了。
|
||||
|
||||
你可以把 IDE 理解成一种专门用来“编辑、管理、运行和调试”各种应用源代码的程序。在真正打包发布之前，不同语言写出来的程序本质上只是特定格式的代码文件而已，你可以用普通文本编辑器打开它们，也可以用 IDE 打开。早期的计算机几乎完全通过终端来操作（只用键盘就能完成所有操作，几乎不需要鼠标），所以早期的 IDE 外观也非常“原始”——除非你额外安装插件来实现简单的交互式界面。
|
||||
|
||||
|
||||
|
||||
终端界面（Terminal）
|
||||
|
||||
图片来源：https://en.wikipedia.org/wiki/File:Emacs-screenshot.png
|
||||
|
||||
一个非常知名、功能成熟的“内置 IDE”叫做 `Vim`。在很多服务器上，你都可以直接用它来编辑文件（服务器通常没有显示屏，只能通过键盘远程操作）。
|
||||
|
||||
|
||||
|
||||
现代 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 作为主要开发工具。
|
||||
|
||||
|
||||
|
||||
# 现代 IDE：VS Code
|
||||
|
||||
Visual Studio Code（简称 VS Code）是由微软开发的一款免费、开源且功能强大的现代代码编辑器。自 2015 年发布以来，凭借优异的性能和灵活性，它迅速成为全球最受欢迎的开发工具之一。
|
||||
|
||||
VS Code 的核心理念之一是“一切皆插件”。不同编程语言可以用来编写不同类型的程序，而每种语言都有自己独特的语法高亮规则和导航能力（比如“跳转到定义”“查找引用”等）。要让一个 IDE 原生支持所有语言几乎是不可能的——从逻辑上讲，你会需要为每一种语言单独准备一个 IDE 才行。
|
||||
|
||||
VS Code 巧妙地通过“插件机制”解决了这一问题。比如，如果你要写 Python，就安装 Python 插件，它会提供 Python 专属的语法高亮、自动补全和代码导航功能；如果你要写 C/C++，则可以安装对应的 C/C++ 插件来获得相应支持。在不安装任何插件的情况下，VS Code 本质上只是一个“高级的文本文件管理器”；当你为某种语言安装了对应插件之后，它就会“变身”成该语言的理想开发工具。
|
||||
|
||||
|
||||
|
||||
除了编写代码以外，你甚至可以把 VS Code 当作编辑 Markdown 文档的工具来使用。
|
||||
|
||||
|
||||
|
||||
总之，你可以在 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 功能区域，体验这些能力。
|
||||
|
||||
|
||||
|
||||
不过，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
|
||||
|
||||
|
||||
|
||||
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 美元。
|
||||
|
||||
|
||||
|
||||
## Qoder
|
||||
|
||||
Qoder 是阿里巴巴推出的一款强调“透明协作”和“增强上下文工程能力”的 AI IDE。它通过 Action Flow 支持把任务拆解成多个步骤，并实时跟踪 AI 的执行过程；还支持多模型动态路由和任务状态机管理，非常适合在中大型项目中做架构治理和对遗留系统进行“反向工程”分析。
|
||||
|
||||
|
||||
|
||||
## CodeBuddy
|
||||
|
||||
CodeBuddy 是腾讯云推出的一款 AI 编程工具，强调对中文指令的支持以及企业级合规能力。它提供代码补全、批量代码审查和多模型切换等功能；其中的 Craft 智能体可以实现多文件代码生成和 API 集成。企业版支持私有化部署，并通过了三级等保认证，适合金融、医疗等对数据安全要求较高的行业。
|
||||
|
||||
|
||||
|
||||
## windsurf（已不推荐）
|
||||
|
||||
Windsurf 最初因其基于 Agent 的 AI 编程能力而受到关注。但由于 2024 年团队调整以及模型权限问题，它的稳定性大幅下降，目前已经不再推荐使用。尽管在前一年它还可以与 Cursor 分庭抗礼，但现在基本可以视为“被淘汰”的工具。
|
||||
|
||||
|
||||
|
||||
## VS Code + Cline
|
||||
|
||||
Cline 是 VS Code（Visual Studio Code）的一款 AI 编程 Agent 插件，可以通过配置不同的 API 端点来灵活切换所使用的大模型。Cline 支持多模态输入、MCP 工具扩展以及成本监控，所有操作都需要用户确认后才会执行。它非常适合用于快速验证想法，或与现有开发流程集成。基础功能是免费的，企业版则支持在私有环境中部署模型。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# 什么是 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/
|
||||
|
||||
|
||||
|
||||
中国版下载地址：
|
||||
|
||||
https://www.trae.cn/
|
||||
|
||||
|
||||
|
||||
## Trae 界面简介
|
||||
|
||||
简单来说，Trae 和 VS Code 看起来几乎一模一样。
|
||||
|
||||
|
||||
|
||||
右侧的侧边栏就是 Copilot 交互窗口，也可以理解为 Agent 窗口。如果你暂时看不到它，可以点击 Trae 右上角的侧边栏图标将其打开。
|
||||
|
||||
|
||||
|
||||
打开侧边栏之后，你会看到一个 `Builder` 选项，这就是 Agent 模式。简单理解，它相当于 z.ai 的“本地版”，可以帮你操作本机环境，安装运行环境、打开网页等。
|
||||
|
||||
|
||||
|
||||
点击 “Builder” 后，你会看到 “Chat” 模式和 “Builder with MCP” 模式：
|
||||
|
||||
* **Chat 模式**：主要用于和当前文件夹里的代码对话，或者当作普通聊天模型来使用。（你可以通过左上角的 “File” 菜单打开一个文件夹，在这个文件夹中进行编辑操作。在这种情况下，Builder 创建或修改的文件都只会发生在这个文件夹内部。）
|
||||
* **Builder with MCP 模式**：为 Agent 提供了更多可用工具（例如把语言模型和其他软件联通起来、查询天气等）。你可以简单理解为：MCP 能让语言模型更方便地调用各种外部工具。
|
||||
|
||||
|
||||
|
||||
在下面的区域，你还会看到模型选择选项，点击即可修改当前使用的大模型。在中国版中，你可以选择使用 Kimi k2 或 GLM 等国内模型；如果你使用的是国际版 Trae，还可以选择 ChatGPT 或 Claude 等海外模型。不过，由于国内大模型发展非常快，Kimi、Qwen、GLM 等在很多任务上的实际体验已经接近 Claude 3.5 或 3.7，对日常开发来说已经完全够用。
|
||||
|
||||
|
||||
|
||||
以上就是对 Trae 的一个简单介绍。接下来，我们可以回顾一下之前在 z.ai 中做过的操作，并尝试在 Trae 中做同样的事情。
|
||||
|
||||
## 使用 Trae 安装 Python 和前端环境
|
||||
|
||||
大多数情况下，我们的 Windows 笔记本电脑默认不会预装前端开发所需的 Node.js 环境，或用于后端 / 通用开发的 Python 环境。我们可以尝试直接在 Trae 的 Agent 模式中跟它对话，让它帮我们安装 Python 环境或 Node.js 环境。
|
||||
|
||||
|
||||
|
||||
## 📚 作业：用 Trae 写你的第一个程序
|
||||
|
||||
接下来，请尝试用 Trae 来完成你的第一个程序！你还记得之前的 AI 贪吃蛇游戏吗？把当时在 z.ai 中使用的那条提示词原封不动地输入到 Trae 的 Agent 模式中，看看会发生什么吧！
|
||||
|
||||
@@ -0,0 +1,943 @@
|
||||
随着大型语言模型（LLM）的广泛应用，企业面临一个现实问题：如何让模型准确回答基于内部文档、实时数据或专业知识的问题？毕竟，模型的训练数据有限且存在时效性，无法覆盖企业特有的业务知识和不断更新的信息。
|
||||
|
||||
一个直观的解决思路是：既然模型的上下文窗口正不断扩大，从8K、128K到如今突破百万token，那何不直接将相关文档塞进提示词，让模型基于这些材料生成答案？
|
||||
|
||||
然而，能够处理长上下文与能在企业级场景中稳定、高效、可控地交付正确答案是截然不同的两件事。盲目依赖长上下文会带来成本飙升、注意力分散、知识更新滞后等一系列严峻挑战。
|
||||
|
||||
正是为了解决这些痛点，一种名为检索增强生成（RAG）的技术应运而生。RAG让大模型在生成答案前先精准检索外部知识，相比简单粗暴地扩展上下文长度，它以更低成本、更高准确性和更强可控性，满足企业级应用对事实准确与知识鲜活的严苛要求，成为构建可信AI应用的关键基石。
|
||||
|
||||
在本篇教程中，我们将系统介绍什么是RAG，追溯其诞生的背景与核心原理，并深入探讨其从基础到进阶的演化路径，以及未来的发展方向。
|
||||
|
||||
# 本节课你将学到
|
||||
|
||||
* RAG的核心价值：深入理解它如何解决长上下文在成本、注意力、知识更新上的核心难题
|
||||
* RAG的工作原理：通过具体案例看它如何完成从检索到生成的闭环
|
||||
* RAG的技术演进脉络：从基础的Naive RAG到Advanced RAG再到模块化的Modular RAG
|
||||
* RAG的模型选型建议：掌握Embedding、Rerank和LLM三大关键模型的评估与选择策略
|
||||
* RAG的企业级实践：学习从数据预处理到系统上线评估的全链路构建指南
|
||||
* RAG的效果评估与调优：了解核心评测指标、主流框架与持续优化的方法
|
||||
* RAG的前沿趋势：探索其与智能体、多模态等技术融合的未来方向
|
||||
|
||||
完成本教程后，你将建立起对 RAG 技术入门级的系统性理解，不仅知其然，更知其所以然。你将获得一个清晰的蓝图，知道如何评估、选型设计一个符合企业级要求的高效、可靠且可控的 RAG 系统，为开发真正的企业级 RAG 应用打下坚实基础。
|
||||
|
||||
# 1. 为什么需要 RAG
|
||||
|
||||
检索增强生成（Retrieval-Augmented Generation，RAG）是当前生成式 AI 中非常重要的一种技术方式。它的基本思路是：在让大模型生成回答之前，先从外部知识库中检索出与问题相关的信息，再把这些检索结果连同用户的问题一起交给模型，让模型在参考真实资料的基础上作答。这个外部知识库可以是企业内部的制度与流程文档、产品知识库，也可以是行业数据库、法规标准库等。
|
||||
|
||||
|
||||
|
||||
但此时我们会有一个疑问：既然大模型本身已经可以“直接回答问题”，为什么还需要额外增加“检索增强生成”这一层？尤其是现在大模型的上下文窗口越来越大，似乎只要把相关资料都提供给模型，让它先理解再回答，也能解决大部分需求。
|
||||
|
||||
真正的区别在于： **“能给出一个回答”** 和**“在真实业务环境中，持续、稳定、可控地给出正确答案”** ，是两件完全不同的事情。如果只是依赖模型参数中的“记忆”，或者仅仅把大量文档放进长上下文中，在企业实际应用中，依然会暴露出至少三类典型问题：
|
||||
|
||||
1. **成本与效率的问题** ：
|
||||
即便大模型的上下文持续扩容，试图将所有文档 “一股脑通通塞进去” 的做法，在实际应用中依然不现实。核心矛盾集中在两点：
|
||||
2. 推理成本与上下文长度呈强正相关：上下文越长，推理成本几乎呈线性甚至超线性上升。以单次调用为例，8K Token 与 200K Token 对应的价格、响应延迟，完全处于不同量级，长上下文的成本门槛显著更高；
|
||||
|
||||
|
||||
> 上下文（context）从意义上指模型在回答当前问题时所“参考”的背景信息与对话历史；从技术上则是指一次推理时输入给模型的 Token 序列（如 system/user 指令、历史消息、检索片段等）的总和。
|
||||
>
|
||||
> “上下文窗口”是这批输入内容的 **容量上限** ：模型一次最多只能“看到”这么多 Token。在当前主流的大模型架构（例如 Transformer）中，这些 Token 会在模型的每一层里彼此做注意力计算、反复参与运算，因此一旦窗口变长、Token 变多，计算量和成本都会成倍甚至指数级增加。
|
||||
>
|
||||
3. 计算资源存在大量浪费：绝大多数任务仅需极少量与当前问题高度相关的信息，将全量文档塞入上下文，会造成严重的计算资源闲置与浪费，进而降低系统吞吐量，拖慢响应速度，最终影响用户体验。
|
||||
4. **注意力与聚焦的问题** ：
|
||||
大模型虽能 “覆盖” 超长上下文，却无法对每一段信息都实现同等质量的利用。当上下文长度达到一定阈值时，模型会出现明显的 “注意力偏差”：
|
||||
5. 注意力衰减：模型对上下文前端、中端的信息关注度会逐渐减弱，更倾向于依赖刚读取的后端文本，导致早期关键信息被 “忽略”；
|
||||
6. 信息干扰：模型容易被上下文内无关、重复甚至冲突的信息 “带偏”，即便最终回答看似逻辑自洽，实际也可能与核心问题脱节，准确性难以保证。
|
||||
可见，若缺乏检索环节进行信息过滤与相关性排序，上下文越长，反而越难确保回答聚焦于真正关键的证据，长上下文的优势会被信息干扰完全抵消。
|
||||
7. **知识更新与可控性的问题** ：
|
||||
若将所有知识完全依赖模型参数存储，或手动复制到提示词中调用，会存在两个难以规避的天然缺陷：
|
||||
8. 知识更新困难：一旦知识发生变更（如政策调整、产品迭代、价格更新等），要么需要重新训练或微调模型 —— 投入高、周期长；要么需要人工逐次维护提示词模板 —— 不仅成本高，还容易因人工操作失误导致信息偏差；
|
||||
9. 可追溯性差：模型回答时究竟依据了哪些具体信息，人们往往难以从 “黑盒化的参数” 或冗长的提示词中定位核心证据，这使得合规审计、风控解释等需要明确 “决策依据” 的工作，面临极大的操作困难。
|
||||
|
||||
在这些现实约束下，RAG 的优势就更加清晰。它的核心做法是：在模型生成答案之前，先通过检索精准定位相关、可靠的信息，让模型只基于必要的知识生成回答。知识可以独立存储在外部知识库中，便于更新与管理；同时，生成结果可以附带引用来源，提升回答的可解释性与可信度。即便未来模型的上下文窗口继续扩大，RAG 依旧能够以较低成本实现知识的高效管理与利用，从而支撑起一个过程可观测、行为可追踪的企业级知识应用体系。
|
||||
|
||||
从企业需求出发，相比只依赖模型自身参数的传统 LLM，RAG 主要解决了企业在落地应用中面临的以下现实问题：
|
||||
|
||||
1. 时效性问题：
|
||||
传统模型对 2024 年之后的新规、新产品、新流程往往不了解，而 RAG 可以直接读取最新的制度文件、业务数据库和知识库内容，无需频繁重新训练模型，就能让回答保持与最新业务同步。
|
||||
2. 专业性问题：
|
||||
通用大模型在医疗、化工、金融等垂直领域，常常存在“懂得不够深、说得不够准”的情况。接入企业自有专业文档和行业标准之后，模型回答可以基于权威资料，显著更贴近真实业务实践。
|
||||
3. “幻觉”问题：
|
||||
通过要求回答尽量基于检索到的文档片段，并能够给出对应的出处引用，可以在机制上减少无依据编造内容的概率，让“说得像真的”更接近“确实是真的”。
|
||||
4. 可解释与可审计问题：
|
||||
纯参数模型给出结论时，往往难以回答“这是从哪条规定推导出来的”。RAG 让每条回答都可以回溯到具体的制度条款、业务文档或历史案例，既方便业务人员抽查和纠错，也为审计、风控、合规部门提供了必要的溯源依据。
|
||||
5. 算力成本与资源效率问题：
|
||||
让大模型在参数中“背下”所有企业知识，往往意味着更大的模型、更高的推理成本。RAG 通过“按需检索”把大部分知识存放在外部向量库和文档库中，使企业可以在较小模型和有限算力条件下，依然获得覆盖面更广、细节更准确的回答能力
|
||||
|
||||
因此，对希望在真实业务场景中长期、稳定、可控地使用大模型的企业而言，RAG 不是一个可有可无的增强选项，而是构建高质量企业知识应用体系时几乎不可缺少的基础技术。
|
||||
|
||||
# 2. 什么是 RAG
|
||||
|
||||
RAG（Retrieval-Augmented Generation，检索增强生成）的核心思路是让大模型在回答问题时，不仅依赖训练阶段学到的静态知识，更能够实时调用外部知识库中的最新、可靠信息。
|
||||
|
||||
在典型的 RAG 系统中，用户的问题不会被直接丢给大模型，而是先由检索模块从企业知识库中找到最相关的文档片段，再将这些内容与原始提问一起组合成完整的上下文，输入给大模型生成回答。这种"先检索、再生成"的方式，让模型能够基于真实参考资料进行推理，而不是仅凭参数中"记住"的知识进行推测。我们可以参考一个典型案例：
|
||||
|
||||
|
||||
|
||||
1. **索引阶段**
|
||||
|
||||
在索引阶段，系统会先处理企业内部文档、网页文章、报告等原始资料，将它们拆分成较小的语义片段（chunks），再用向量模型为每个片段生成向量表示并建立索引。这样，后续接收到用户问题时，就可以在向量空间中快速找到“语义最相近”的几段内容。
|
||||
|
||||
在图中，这一阶段对应右上角紫色区域 “Indexing”。从 “Documents” 出发，经由 “Chunks / Vectors” 到 “embeddings” 的那一部分，就是在说明文档被切块并转换为向量、写入索引的过程。具体过程如下：
|
||||
|
||||
* 文档被划分为若干个语义相对完整的 chunks，每个 chunk 可能对应一小段新闻、一段说明或一段分析。
|
||||
* 每个 chunk 会通过 embedding 模型转换成高维向量，并存入向量索引中。
|
||||
* 这个索引支持后续基于相似度的检索，为回答问题提前准备好“可被查阅的知识库”。
|
||||
|
||||
2. **检索阶段 + 基于检索结果生成答案**
|
||||
|
||||
当用户提出问题后，系统会先从索引中检索相关内容，再把问题和检索到的文本一并交给大模型生成答案。图中从上到下、从右到左的几个关键区域，正好对应这一整条流程。
|
||||
|
||||
（1）用户输入问题——图中黄色区域 Input – Query
|
||||
|
||||
> “How do you evaluate the fact that OpenAI's CEO, Sam Altman, went through a sudden dismissal by the board in just three days, and then was rehired by the company, resembling a real-life version of 'Game of Thrones' in terms of power dynamics?”
|
||||
>
|
||||
> “你如何评价这样一件事：OpenAI 的 CEO Sam Altman 被董事会突然解职，仅仅三天后又被公司重新聘回，在权力博弈上几乎像现实版《权力的游戏》？”
|
||||
|
||||
这一大段文字就是图中 “Query” 方框里的内容，对应“用户发起的自然语言提问”。系统会将这段话向量化，并据此去右上角的索引里查找相关文档片段。
|
||||
|
||||
（2）检索到的相关文档——图中右下角粉色区域 Relevant Documents
|
||||
|
||||
检索完成后，系统会得到若干个与问题最相关的文档块，它们在图中以三个 Chunk 的形式展示：
|
||||
|
||||
> “Sam Altman Returns to OpenAI as CEO, Silicon Valley Drama Resembles the 'Zhen Huan' Comedy”
|
||||
> “Sam Altman 回归担任 OpenAI CEO，这场硅谷大戏宛如一出《甄嬛传》式的宫斗喜剧。”
|
||||
>
|
||||
> “The Drama Concludes? Sam Altman to Return as CEO of OpenAI, Board to Undergo Restructuring”
|
||||
> “大戏要落幕了吗？Sam Altman 将重返 OpenAI CEO 职位，董事会则将进行重组。”
|
||||
>
|
||||
> “The Personnel Turmoil at OpenAI Comes to an End: Who Won and Who Lost?”
|
||||
> “OpenAI 的人事动荡告一段落：谁赢了，谁输了？”
|
||||
|
||||
（3）组合 Prompt 并生成回答——图中蓝色区域 LLM / Combine Context and Prompts
|
||||
|
||||
系统随后会将“用户原始问题 + 检索到的 chunks”组合成一个完整的 Prompt，发给大模型。图中中下部、靠中央的虚线框，就是这个 Prompt 的示例内容：
|
||||
|
||||
> “Question:
|
||||
> How do you evaluate the fact that the OpenAI's CEO, … … dynamics?
|
||||
>
|
||||
> Please answer the above questions based on the following information :
|
||||
> Chunk 1 :
|
||||
> Chunk 2 :
|
||||
> Chunk 3 :”
|
||||
>
|
||||
> “问题：
|
||||
> 你如何评价 OpenAI 的 CEO …… 这件事中的权力博弈？
|
||||
>
|
||||
> 请基于下面提供的信息来回答上述问题：
|
||||
> Chunk 1：
|
||||
> Chunk 2：
|
||||
> Chunk 3：”
|
||||
|
||||
（4）有无 RAG 的回答对比——图中左下角灰色 / 黄色区域 Output – Answer
|
||||
|
||||
最后，大模型基于这些信息生成答案，结果展示在图的左下角 “Answer” 区域。这里同时给出了“未使用 RAG”和“使用 RAG”两种情况下的输出示例。不用 RAG 时，模型缺乏外部资料，只能给出非常模糊的回应，对应灰色框里那段话：
|
||||
|
||||
> “… I am unable to provide comments on future events. Currently, I do not have any information regarding the dismissal and rehiring of OpenAI's CEO …”
|
||||
>
|
||||
> “……我无法就未来事件发表评论。目前我没有关于 OpenAI CEO 被解雇和重新聘用的任何信息……”
|
||||
|
||||
使用 RAG 时，模型可以利用刚才检索到的新闻和分析，给出更有信息量的回答，对应黄色框中那段文本：
|
||||
|
||||
> “… This suggests significant internal disagreements within OpenAI regarding the company's future direction and strategic decisions. All of these twists and turns reflect power struggles and corporate governance issues within OpenAI …”
|
||||
>
|
||||
> “……这表明 OpenAI 内部在公司未来方向和战略决策上存在重大分歧。这一连串的反复与曲折，反映出 OpenAI 内部的权力斗争以及公司治理方面的问题……”
|
||||
|
||||
以上展示了一个典型 RAG 系统的完整流程，让我们从整体上理解了系统包含哪些核心环节、信息如何在各阶段流转。但是，检索时如何进行向量匹配？提示词如何组织才能让模型更好地利用检索到的内容？这些决定 RAG 实际效果的技术细节，目前仍是"黑盒"。接下来，我们将深入 RAG 的内部机制，从向量化原理、相似度计算、到提示词工程等关键环节，逐步拆解 RAG 究竟是如何工作的。
|
||||
|
||||
# 3. RAG 如何工作
|
||||
|
||||
我们可以通过一个“苹果”的知识库问答案例，逐步拆解它的关键环节。
|
||||
|
||||
## 3.1 文档向量化阶段
|
||||
|
||||
假设我们有一个简化的知识库，包含以下三个文档片段：
|
||||
|
||||
1. 文档片段A：苹果公司于1976年4月1日由史蒂夫·乔布斯、史蒂夫·沃兹尼亚克和罗纳德·韦恩创立，总部位于加利福尼亚州库比蒂诺。
|
||||
2. 文档片段B：苹果是一种水果，富含维生素C和膳食纤维，有助于消化和免疫系统健康。
|
||||
3. 文档片段C：苹果公司在2007年推出了第一款iPhone，彻底改变了智能手机行业。
|
||||
|
||||
当我们使用嵌入模型（如 OpenAI 的 text-embedding-ada-002 或开源的 BGE 模型）处理文档时，每个文档片段会被转换为高维向量（通常含 768、1024 或 1536 个维度）。
|
||||
|
||||
> “向量”本质是由多个数值组成的数组，每个维度的数值都对应文本某一维度的语义特征，比如 “猫” 的向量中，可能有维度对应 “哺乳动物”“家养宠物”“有毛” 等属性，最终通过整体数值组合精准捕捉文本的语义含义，让计算机能 “读懂” 文本间的关联。
|
||||
|
||||
简化示例（实际向量维度高得多，这里仅示意）：
|
||||
|
||||
* 文档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）用于之后的检索召回工作。
|
||||
|
||||
> 数据库是按特定结构存储、管理数据的系统，核心功能是实现数据的有序存储与高效存取，常见于通讯录、电商商品库等场景。
|
||||
>
|
||||
> 而向量数据库是数据库的细分类型，区别于传统数据库存储文本、表格等数据的逻辑，它专门用于存储 “向量”（高维数值数组），并优化了向量相似性检索能力，以适配 AI 场景下的高维数据管理需求。
|
||||
|
||||
## 3.2 用户查询检索、回复阶段
|
||||
|
||||
在知识库完成向量化存储后，RAG系统便能够支持用户的实时查询操作。当用户提出问题时，系统会执行一套连贯的流程：先将问题转化为向量，再通过相似度计算从知识库中召回最相关的信息片段，最终将这些片段作为生成答案的依据。我们通过三个具体查询来完整呈现这一过程。
|
||||
|
||||
### 查询一：“苹果公司是什么时候创立的？”
|
||||
|
||||
在查询向量化阶段，此问题被嵌入模型转换为一个语义向量，例如 `[0.82, -0.21, 0.38, -0.58, 0.15, 0.76, ...]`。该向量在数值模式上，与之前存储的“文档A向量”（关于公司创立）`[0.85, -0.23, 0.41, -0.56, 0.12, 0.78, ...]`高度相似。
|
||||
|
||||
接下来系统将进行相似度检索 (Top-K, K=2)操作，计算该查询向量与知识库中所有文档向量的余弦相似度（一种衡量向量方向接近程度的指标）。结果如下：
|
||||
|
||||
* 与文档A（公司创立）相似度：0.97（高度相关）
|
||||
* 与文档C（iPhone发布）相似度：0.88（相关，同属公司主题）
|
||||
* 与文档B（水果营养）相似度：0.12（几乎不相关）
|
||||
|
||||
> Top-K 是向量检索场景中常用的筛选策略，核心含义是 “从所有匹配结果中，按相似度从高到低排序后，选取排名前 K 个的结果”；而 K=2 则是对该策略的具体数值定义，即明确要求系统仅保留相似度排名前 2 的文档向量，过滤掉其余相似度更低的结果，以确保后续仅基于最相关的 2 个文档片段生成答案。
|
||||
|
||||
此时根据相似度值过滤后的返回结果我们叫做召回结果。系统根据相似度分数从高到低，返回Top-2的文档片段作为证据：
|
||||
|
||||
1. 文档A (相似度0.97)：“苹果公司于1976年4月1日由史蒂夫·乔布斯、史蒂夫·沃兹尼亚克和罗纳德·韦恩创立，总部位于加利福尼亚州库比蒂诺。”
|
||||
2. 文档C (相似度0.88)：“苹果公司在2007年推出了第一款iPhone，彻底改变了智能手机行业。”
|
||||
|
||||
在根据检索结果对话的大模型回复阶段，系统会构建如下所示的完整对话输入，将召回的结果放入参考信息中，和系统提示一起发送给LLM：
|
||||
|
||||
```Plain
|
||||
【系统指令 (System Prompt)】
|
||||
你是一个专业的问答助手。请严格根据用户提供的“参考信息”来回答问题。
|
||||
如果参考信息中包含问题答案，请直接基于该信息进行回答。
|
||||
如果参考信息中不包含问题答案，请明确告知用户“根据现有资料无法回答该问题”，切勿自行编造信息。
|
||||
请在回答中注明依据的信息点。
|
||||
【参考信息 (Retrieved Context)】
|
||||
苹果公司于1976年4月1日由史蒂夫·乔布斯、史蒂夫·沃兹尼亚克和罗纳德·韦恩创立，总部位于加利福尼亚州库比蒂诺。
|
||||
苹果公司在2007年推出了第一款iPhone，彻底改变了智能手机行业。
|
||||
【用户问题 (User Query)】
|
||||
苹果公司是什么时候创立的？
|
||||
```
|
||||
|
||||
LLM接收到上述结构化输入后，会遵循系统指令，将“参考信息”视为回答问题的唯一可信来源。其最终回复将类似：根据提供的参考信息，苹果公司于 1976年4月1日 创立。【依据：信息1】”
|
||||
|
||||
### 查询二：“吃苹果有什么好处？”
|
||||
|
||||
在查询向量化阶段，此问题被嵌入模型转换为一个语义向量，例如 `[-0.08, 0.92, -0.31, 0.71, -0.85, 0.08, ...]`。该向量在数值模式上，与之前存储的“文档B向量”（关于水果营养）`[-0.12, 0.95, -0.34, 0.67, -0.89, 0.05, ...]`高度相似。
|
||||
|
||||
接下来系统将进行相似度检索 (Top-K, K=2) 操作，计算该查询向量与知识库中所有文档向量的余弦相似度。结果如下：
|
||||
|
||||
* 与文档B（水果营养）相似度：0.95（高度相关）
|
||||
* 与文档C（iPhone发布）相似度：0.18（几乎不相关）
|
||||
* 与文档A（公司创立）相似度：0.15（几乎不相关）
|
||||
|
||||
系统根据相似度分数从高到低，返回 Top‑2 的文档片段作为证据：
|
||||
|
||||
1. 文档B (相似度0.95)：“苹果是一种水果，富含维生素C和膳食纤维，有助于消化和免疫系统健康。”
|
||||
2. 文档C (相似度0.18)：“苹果公司在2007年推出了第一款iPhone，彻底改变了智能手机行业。”（相关性极弱，实际可能被阈值过滤）
|
||||
|
||||
在根据检索结果对话的大模型回复阶段，系统会构建如下所示的完整对话输入，将召回的结果放入参考信息中，和系统提示一起发送给LLM：
|
||||
|
||||
```Plain
|
||||
【系统指令 (System Prompt)】
|
||||
你是一个专业的问答助手。请严格根据用户提供的“参考信息”来回答问题。
|
||||
如果参考信息中包含问题答案，请直接基于该信息进行回答。
|
||||
如果参考信息中不包含问题答案，请明确告知用户“根据现有资料无法回答该问题”，切勿自行编造信息。
|
||||
请在回答中注明依据的信息点。
|
||||
【参考信息 (Retrieved Context)】
|
||||
苹果是一种水果，富含维生素C和膳食纤维，有助于消化和免疫系统健康。
|
||||
苹果公司在2007年推出了第一款iPhone，彻底改变了智能手机行业。
|
||||
【用户问题 (User Query)】
|
||||
吃苹果有什么好处？
|
||||
```
|
||||
|
||||
LLM接收到上述结构化输入后，其最终回复将类似：
|
||||
|
||||
> 根据提供的参考信息，苹果富含维生素C和膳食纤维，食用苹果有助于消化以及免疫系统健康。【依据：信息1】
|
||||
|
||||
### 查询三：“今天天气怎么样”
|
||||
|
||||
在查询向量化阶段，此问题被嵌入模型转换为一个与气象、天气相关的语义向量，例如 `[0.10, -0.05, 0.30, -0.12, 0.21, 0.08, ...]`。该向量在数值模式上，与知识库中所有关于“苹果（公司/水果）”的文档向量在语义空间中距离较远，因此不会出现显著相似性。
|
||||
|
||||
接下来系统将进行相似度检索 (Top-K, K=2) 操作，计算余弦相似度。由于问题主题与知识库内容无关，整体相似度得分都很低。结果如下：
|
||||
|
||||
* 与文档B（水果营养）相似度：0.18（极低）
|
||||
* 与文档C（iPhone发布）相似度：0.10（几乎不相关）
|
||||
* 与文档A（公司创立）相似度：0.08（几乎不相关）
|
||||
|
||||
Top-K 仍会返回相似度排名前 K 个结果，但在该场景下，这些结果并不能提供有效证据。实际系统常会结合“最低相似度阈值”直接返回空召回，即没有任何召回的结果，参考信息为 0，以减少无关信息干扰。
|
||||
|
||||
1. 文档B (相似度0.18)：“苹果是一种水果，富含维生素C和膳食纤维，有助于消化和免疫系统健康。”
|
||||
2. 文档C (相似度0.10)：“苹果公司在2007年推出了第一款iPhone，彻底改变了智能手机行业。”
|
||||
|
||||
在根据检索结果对话的大模型回复阶段，系统会构建如下完整输入：
|
||||
|
||||
```Plain
|
||||
【系统指令 (System Prompt)】
|
||||
你是一个专业的问答助手。请严格根据用户提供的“参考信息”来回答问题。
|
||||
如果参考信息中包含问题答案，请直接基于该信息进行回答。
|
||||
如果参考信息中不包含问题答案，请明确告知用户“根据现有资料无法回答该问题”，切勿自行编造信息。
|
||||
请在回答中注明依据的信息点。
|
||||
【参考信息 (Retrieved Context)】
|
||||
苹果是一种水果，富含维生素C和膳食纤维，有助于消化和免疫系统健康。
|
||||
苹果公司在2007年推出了第一款iPhone，彻底改变了智能手机行业。
|
||||
【用户问题 (User Query)】
|
||||
今天天气怎么样？
|
||||
```
|
||||
|
||||
LLM接收到上述结构化输入后，会先判断参考信息是否包含“天气/气象/实时数据”等直接信息；在确认参考信息与问题无关后，会遵循系统指令执行“无法回答”。其最终回复将类似：
|
||||
|
||||
> 根据现有资料无法回答“今天天气怎么样”，因为参考信息仅包含与苹果（水果营养、苹果公司产品）相关内容，不包含天气信息或实时气象数据。【依据：参考信息中无天气相关信息】
|
||||
|
||||
通过以上三个实例可以看出，在检索增强生成的大模型对话阶段中，系统指令设定了LLM的角色和回答规则，检索证据提供了具体、可信的作答素材，用户问题则明确了任务目标。这种结构化的输入方式，正是RAG技术能够有效引导并约束原本可能产生“幻觉”的大模型，使其输出稳定、可靠答案的关键所在。它确保了大模型的能力被精准地应用于理解与组织已有信息，而非无根据地创造信息。
|
||||
|
||||
# 4. RAG 技术演进史
|
||||
|
||||
RAG 技术并非诞生于大模型时代，在更早期的研究中就已有雏形。从发展脉络来看，RAG 的出现源于对传统 LLM 局限性的认识。早期的大语言模型主要依赖预训练数据，这些数据往往在模型训练完成后就固定下来，无法获取后续更新的信息。例如，GPT-3 等模型的知识截止点通常在训练数据收集的日期之后，无法获取新知识。此外，重新训练或微调 LLM 以适应特定领域需要大量资源和专业知识，成本高昂且难以快速迭代。
|
||||
|
||||
RAG 技术的起源可以追溯到 2017 年的 DrQA 框架，该框架首次尝试将检索机制与语言模型相结合。随后，2020 年引入的 Dense Passage Retrieval (DPR) 标志着 RAG 技术的重大突破，它利用预训练的神经网络模型进行语义检索，而非传统的 TF-IDF 或 BM25 等基于词频的方法。2021 年，RAG 被正式提出并系统化，成为解决 LLM 知识截止和幻觉问题的标准方法。
|
||||
|
||||
整体来看，RAG 的演进大致可以分为三个阶段：
|
||||
|
||||
|
||||
|
||||
## 4.1 第一代 RAG：Naive RAG（基础检索增强）
|
||||
|
||||
Naive RAG可以理解为基础的 RAG 形态，它在工程上非常直接，典型流程可以概括为“三步走”：第一步是文档预处理与索引，将原始文档经过清洗之后，按固定长度切分成若干文本块（chunks），再用嵌入模型将每个文本块编码为向量，写入向量数据库；第二步是基于相似度的检索，将用户的自然语言问题编码成向量，在向量库中执行 Top‑K 相似度搜索，取回相似度最高的若干文本块；第三步则是简单拼接后的增强生成，把这些检索出来的文本块和原始问题直接拼在一起，构成一个长提示词交给 LLM，由模型在这个上下文基础上生成回答。
|
||||
|
||||
这一阶段的价值在于，以极低门槛验证了“先查再答”的思路确实有效：相比完全依赖模型内部记忆，已经能明显缓解知识截止和部分幻觉问题，在早期的原型系统和示例工程中发挥了重要作用。这使得 RAG 从一开始就具备了很强的实用性，成为大量 Demo、原型系统和入门教程的首选方案。
|
||||
|
||||
然而，这一代 RAG 的局限同样非常明显。首先，文本分块策略通常比较粗糙，大多采用固定长度切分，容易把一个完整的语义段落从中间“截断”，也可能把多个主题混杂在同一个块里，既影响检索准确性，也会给 LLM 的理解带来额外负担。其次，检索信号非常单一，往往只依赖向量相似度进行排序，没有利用关键词、时间戳、来源可信度、访问权限等更丰富的结构化线索。再次，检索结果几乎不经过筛选和治理，噪音、重复甚至彼此矛盾的片段都会原样塞进上下文，使得本来就紧张的上下文窗口被大量“低价值信息”占据。
|
||||
|
||||
可以说，第一代 RAG 解决了“要不要检索”的问题，但在“如何更好地检索”和“检回来的东西如何更合理地用起来”这两个问题上，还停留在相当原始的阶段。
|
||||
|
||||
## 4.2 第二代 RAG：Advanced RAG（检索与上下文的精细化优化）
|
||||
|
||||
随着 RAG 应用从 Demo 走向真实业务场景，系统对稳定性、可控性以及结果质量的要求迅速提高。此时出现的第二代 RAG，通常可以笼统地称作 Advanced RAG，它仍然遵循先检索、再生成的方法，但在检索前和检索后两个环节引入了系统化的精细化优化策略。换句话说，不再满足于“能不能检到东西”，而是要“把该存的东西存好，把该问的问题问清，把检回来的上下文治理好”。
|
||||
|
||||
在检索前，重点是把“存什么”和“怎么问”处理好：
|
||||
|
||||
* 在索引端，从固定长度切分演进到语义感知分块与分层索引，例如按章节、小节、段落或句子边界进行切分，辅以滑动窗口和多粒度索引结构。
|
||||
* 为每个文档块附加丰富的元数据，例如来源、时间、作者、主题、文档类型等，为后续的过滤和排序提供更多维度。
|
||||
* 在查询端，对用户原始问题进行重写、扩展和拆分，例如通过 Query Rewrite、多路查询（Multi-Query）、子问题分解（Sub-Query）、Step-back Prompting 等方式，将含糊或口语化的问题转换为更利于检索理解的表达。
|
||||
> 1. Query Rewrite（查询重写）
|
||||
>
|
||||
> 核心是将用户模糊、口语化或不规范的原始查询，转化为检索系统更易理解的标准化表述，补充关键信息、修正歧义。
|
||||
>
|
||||
> * 用户原始问题为 “咋查明天北京的天气啊”，会去除 “咋”“啊” 等口语化词汇，补充 “实时”“全天” 等关键限定，重写为 “查询北京市明日全天实时天气”；
|
||||
> * 用户原始问题为 “推荐好看的电影”，若结合用户历史行为发现其常看悬疑片，会补充 “2024 年高分”“悬疑题材” 等信息，重写为 “推荐 2024 年高分悬疑题材电影”。
|
||||
>
|
||||
> 2. Multi-Query（多路查询）
|
||||
>
|
||||
> 基于原始问题生成多个 “语义相关但角度不同” 的查询语句，避免单一查询遗漏潜在结果，覆盖用户未明确的潜在需求。
|
||||
>
|
||||
> * 用户原始问题为 “如何给刚满月的宝宝拍嗝”，会生成聚焦 “姿势” 的查询：“新生儿拍嗝的正确姿势”；
|
||||
> * 生成聚焦 “防吐奶” 的查询：“满月宝宝拍嗝避免吐奶的方法”；
|
||||
> * 生成聚焦 “月龄适配” 的查询：“婴儿拍嗝的步骤（0-1 个月）”；
|
||||
> * 生成聚焦 “新手场景” 的查询：“新手爸妈给满月宝宝拍嗝技巧”。
|
||||
>
|
||||
> 3. Sub-Query（子问题分解）
|
||||
>
|
||||
> 针对包含多个诉求的复合问题，拆分为独立、简单的子查询，让检索系统针对单一诉求精准匹配数据，避免信息混杂缺失。
|
||||
>
|
||||
> * 用户原始复合问题为 “北京到上海的高铁，明天有哪些班次？票价多少？需要坐多久？”，会拆解出聚焦 “班次” 的子查询：“北京市至上海市 明日高铁班次表”；
|
||||
> * 拆解出聚焦 “票价” 的子查询：“北京到上海高铁 二等座 / 一等座票价”；
|
||||
> * 拆解出聚焦 “时长” 的子查询：“北京到上海高铁 行驶时长（最快 / 平均）”。
|
||||
>
|
||||
> 4. Step-back Prompting（回溯提示）
|
||||
>
|
||||
> 先生成 “比原始问题更宏观的上位问题”，再基于上位逻辑回推检索方向，解决原始问题因聚焦细节导致的理解偏差。
|
||||
>
|
||||
> * 用户原始问题为 “为什么 2024 年某国产新能源汽车品牌的销量突然下降？”，第一步生成宏观上位问题：“影响新能源汽车品牌短期销量波动的核心因素有哪些？”（如产品迭代、竞品动作、政策变化、市场需求等）；
|
||||
> * 第二步基于上位问题逻辑，生成具体检索方向：“2024 年某国产新能源品牌 产品更新情况”“2024 年新能源汽车市场 竞品定价策略”“2024 年新能源汽车补贴政策调整”。
|
||||
>
|
||||
|
||||
在检索后，重点是把“取回来的内容”治理好：
|
||||
|
||||
* 使用专门的 Rerank 模型或 LLM 对候选文档进行重新排序，确保最关键、最贴近问题的内容优先进入上下文。
|
||||
> Rerank 模型是信息检索流程中的关键组件，主要用于对 “召回阶段” 初步筛选出的候选结果进行二次排序 —— 它会借助更复杂的语义理解能力（常基于 Transformer 等深度学习架构），分析用户需求与候选结果的深层关联，修正初步排序中可能存在的语义偏差，最终让更贴合用户需求的结果排在更靠前的位置，提升用户获取有效信息的效率。
|
||||
>
|
||||
* 对检索结果进行筛选、去重与压缩，去掉明显无关或高度重复的片段，缓解长上下文中部信息被忽略的问题。
|
||||
* 在必要时，结合轻量的模型微调，使 LLM 更倾向于依据检索证据作答，并在回答中附带引用或出处信息。
|
||||
|
||||
总体来看，第二代检索增强生成技术其关注点不再局限于 “是否需要检索”“能否检索到信息” 这两个基础问题，而是进一步聚焦于三个更大的挑战：“能否精准定位到真正关键的段落内容”“传递给大模型的上下文是否简洁有序、具备清晰结构且易于高效利用”“当面临信息噪音、内容冲突或多资料源查找需求时，系统整体性能是否依然稳健可靠”。
|
||||
|
||||
从大量实验验证与工程落地实践来看，Advanced RAG 在问答准确率、幻觉抑制能力、系统鲁棒性及结果可解释性等关键指标上，均显著优于 Naive RAG。也正因此，Advanced RAG 已逐步取代传统方案，成为当前工业界构建 RAG 系统的主流技术范式。
|
||||
|
||||
## 4.3 第三代 RAG：Modular RAG
|
||||
|
||||
在企业级的复杂应用场景中，需求往往跨越多个领域。在这种情况下，RAG系统若仅采用检索、重排、生成这样的单一线性处理方式，常常难以应对：
|
||||
|
||||
1. 同一系统既要支持简单 FAQ，又要生成长篇报告、进行代码检索或调用数据库。
|
||||
2. 需要同时接入向量库、全文检索、关系数据库、知识图谱以及外部搜索引擎等多种数据源。
|
||||
3. 需要在多轮交互中保持对用户偏好、历史决策的记忆，并对输出结果实施合规审核和溯源。
|
||||
|
||||
在这样的背景下，RAG 的系统形态开始向模块化演进。Modular RAG 不再被看作一条固定的流水线，而是由一组可插拔、可替换、可组合的功能模块组成，通过编排逻辑按需组合执行。典型模块包括：
|
||||
|
||||
1. 查询理解与路由模块
|
||||
用于意图识别、问题重写、子任务拆解和路径选择，决定一条请求是主要依赖内部知识，还是外部检索，抑或需要调用特定工具或数据库。
|
||||
例如，用户问「这条错误日志代表什么问题？」系统会将其路由到代码与日志知识库；而问「最近该行业的监管新规有哪些变化？」则更适合走互联网搜索或合规法规库。
|
||||
2. 多源检索与融合模块
|
||||
同时连接向量数据库、全文检索系统、结构化数据库与知识图谱，对不同数据源进行查询，并将结果进行统一的融合与排序。
|
||||
例如，在做「客户年度分析报告」时，一部分信息来自 CRM 数据库（如客户成交额），一部分来自文档库（如项目复盘），还可能需要从知识图谱中补充行业关系，最终由该模块将多源结果合并成一份有序的证据集。
|
||||
3. 记忆与个性化模块
|
||||
维护长期用户画像、短期会话记忆和领域知识缓存，使系统能够在长期交互中不断积累和利用历史信息。
|
||||
比如，系统记住某位用户偏好「先给结论再给细节」，以及他所在的业务线与常用术语，下次回答时会自动采用对应风格，并优先使用与该业务线相关的案例和数据。
|
||||
4. 任务适配与治理模块
|
||||
面向不同任务加载对应的适配器，对输出格式、语气、风格进行约束，并结合事实核查、风险过滤和引用对齐等机制，对生成结果进行治理。
|
||||
例如，同样是基于同一批检索结果，为产品经理生成的是结构化 PRD 模板，为法务人员则是正式合规审查意见；在此过程中，该模块会对关键事实进行二次核查，并强制要求给出引用来源。
|
||||
|
||||
总的来说，传统 RAG 往往是一轮检索配合一轮生成就结束，而 Modular RAG 则打破了这种单一流程。当系统在生成过程中发现信息不足时，可以主动触发新的检索轮次，甚至多次往返检索与生成，以完成更复杂的任务。
|
||||
|
||||
进一步地，模型还可以学习自我决策：对于把握较大的问题直接基于内部知识或短上下文作答；遇到不确定的情况时才发起检索或调用外部工具，从而在保证质量的前提下提高效率、节约资源。对于那些表达不清、信息缺失严重的查询，系统甚至可以先由大模型生成一个假设性的答案或中间文档，再以此作为“线索”去检索真实文档，不断逼近可靠信息源。
|
||||
|
||||
在这一阶段，RAG 已经不再只是给大模型补几段参考资料的简单组件，而逐步演变为企业级智能应用的中枢式知识编排层，负责在多数据源、多工具、多任务之间进行协调与调度。
|
||||
|
||||
# 5. 从 Demo 到企业级的 RAG 系统
|
||||
|
||||
从企业工程实践的角度来看，RAG 系统的构建不能仅局限于检索增强生成技术本身，前面提到的内容更多是一个 Demo 级别的介绍。由于实际业务场景中的数据往往存在质量参差不齐、格式混乱等问题，因此需要在数据预处理、清洗及导入环节投入更多精力，同时在各个关键节点做好模型选型。
|
||||
|
||||
一个完整的企业级 RAG 系统通常可以划分为三个核心模块：版面分析与知识采集、知识库构建、以及基于 RAG 的知识问答服务。在整个技术链路中，涉及多个关键模型的选型决策，包括 Embedding 模型、Rerank 模型和 LLM 模型。只有在每个环节都做出合理的技术选型，才能确保系统达成最佳效果。
|
||||
|
||||
1. 版面分析与本地知识文件读取
|
||||
|
||||
这一模块负责将各种格式的本地知识资产转换为可用于检索的文本。输入可能包括 PDF、TXT、HTML、Word、Excel、PPT 等文档，也包括 PNG、JPG 等图片类扫描文件，甚至是语音录音。
|
||||
|
||||
系统需要针对不同格式做解析，对文本文档做版面分析与结构抽取，区分标题、正文、表格、页眉页脚等元素，恢复合理的阅读顺序。对图片类文件进行 OCR 识别，对语音进行语音转写（ASR），最终统一转换为较为干净的知识文本，并尽量保留一些基础元信息，如文档名、章节、页码、时间等,为后续切分和索引打下基础。
|
||||
|
||||
2. 知识库构建（切分、Embedding、索引）
|
||||
|
||||
在拿到清洗后的知识文本后，需要先进行合理的文本切分（Chunking），把长文档拆成若干语义相对完整、长度适中的文本块,通常按段落、标题结构或滑动窗口切分，同时保留每个块对应的文档来源和元数据。
|
||||
|
||||
随后，使用选定的 Embedding 模型，如 text-embedding-3-small、Sentence Transformers、BGE 等，对每个文本块计算向量表示，并基于这些向量构建向量索引，如使用 Faiss、Milvus、向量搜索服务等，就得到一个可按语义相似度进行快速查询的知识库。至此，我们完成了知识转换为可检索向量的核心步骤。
|
||||
|
||||
3. 基于 RAG 的知识问答（召回、排序、拼接、生成）
|
||||
|
||||
在在线问答阶段，用户首先发出查询请求，系统会对查询进行 Embedding，得到查询向量，并在向量索引中检索出一批最相似的文本块（Top N），这是粗排阶段。在此基础上，可以选用 Rerank 模型，如 BGE Reranker 或 LLM 充当 Reranker，对查询与文档对进行精排打分，从中选出 Top K 个真正最相关的文档作为知识上下文。
|
||||
|
||||
接着，结合精心设计的系统提示词如"请严格基于以下资料回答"等等，将用户查询和检索出的文档片段进行拼接，把这个合并后的提示发给 LLM，由它在检索得到的证据基础上生成最终答案，并在需要时附上引用或出处。
|
||||
|
||||
## 5.1 模型选型
|
||||
|
||||
接下来我们关注各环节的模型选型，一个完整的 RAG 系统通常涉及三类核心模型：即 Embedding 模型、Rerank 模型和大语言模型。这三类模型各司其职，共同构成了从知识检索到答案生成的完整流程。其中，Embedding 模型负责将文本转化为可检索的语义向量，Rerank 模型对初步检索结果进行精细筛选与重排序，大语言模型则基于筛选后的知识上下文生成最终答案。
|
||||
|
||||
### 5.1.1 Embedding model
|
||||
|
||||
在 RAG 系统中，Embedding 模型的作用是将文本，如用户查询和知识库内容，转换为高维向量。语义相近的文本，其向量在空间中的位置也更接近，这使得系统能够通过向量相似度快速定位相关知识。因此，选择合适的 Embedding 模型是构建高性能 RAG 系统的关键一步，直接决定了召回阶段的质量。
|
||||
|
||||
为了选出好的模型，我们在这里介绍一个系统化的评价基准：MTEB（大规模文本嵌入评测基准）
|
||||
|
||||
MTEB为各类Embedding模型提供了一个统一、客观的评估框架。它通过8大类任务、56个数据集，全面评测模型在检索、聚类、分类、重排序、文本匹配、语义相似度等多种场景下的表现。模型在MTEB上的整体得分，能够反映其向量表示能力的通用性和稳健性，可作为选型的重要数据参考。最新排名和详细结果可通过 [HuggingFace MTEB Leaderboard](https://huggingface.co/spaces/mteb/leaderboard) 查看。
|
||||
|
||||
|
||||
|
||||
尽管榜单上存在大量模型，你可以根据实际需求进行选择，并不需要掌握所有的模型（一般来说，选择大模型厂商自带的 Embedding 模型，或者使用云服务平台部署对外使用的模型就大概率不会错，因为这个是大多人检验后的标准），你还可以在侧边栏中选择具体的类别或者语言进行筛选：
|
||||
|
||||
|
||||
|
||||
此外，在筛选 Embedding 模型时，需重点关注直接影响 RAG 性能的两个核心参数：维度和上下文长度。其中，维度是指模型输出向量的维度数（如 128 维、768 维），它本质上反映了描述语义信息时所使用的“特征数量”。维度越高，向量能刻画的语义细节越丰富、区分度越强，例如一个 768 维的向量可以从品种、口感、产地等数百个角度精细表征“苹果”，从而更适用于医疗、法律等需要精准检索的专业场景；维度越低，则计算与存储成本越小、检索速度越快，适合千万级文档等高并发、强实时性要求的通用场景。
|
||||
|
||||
另一个参数Context Length（上下文长度） ，指 Embedding 模型单次可处理的最大文本长度（以 token 为单位，1 英文 token 约 0.75 个单词、1 中文 token 约 1 个汉字），超出部分会被截断：它直接决定模型能否完整理解文本，若长度不足导致信息丢失，会大幅降低检索准确性。因此处理用户短句、问答对这类短文本时，选 512-1024token 的模型即可；处理论文、报告等长文本时，需选 2048token 及以上的模型以避免关键信息丢失。
|
||||
|
||||
以下是几种常见Embedding模型的横向对比，你需要在实际调用过程中综合成本、性能进行选择最佳模型，没有最好的模型，只有对比多个模型的效果选出最合适的模型。
|
||||
|
||||
| 模型名称 | 模型规模 | 核心优势 | 适用场景 |
|
||||
| ----------------------------- | -------------------------------- | ---------------------------------------------- | ----------------------------------------------------------- |
|
||||
| OpenAI text-embedding-3-large | 闭源API | MTEB测试集上长期领先，成熟稳定 | 追求极致性能且预算充足的云端API场景，适合对延迟不敏感的应用 |
|
||||
| jina-embeddings-v2 | 支持长文本（最高8K上下文） | 异步编码设计，处理长文档检索时强有力 | 需要长上下文理解的文档分析、法律合规、学术文献检索 |
|
||||
| multilingual-e5-large | Large规模 | 经典的多语言备选方案 | 跨语言RAG、国际化产品、多语种客服系统 |
|
||||
| Qwen/Qwen2-Embedding-8B | 8B参数，支持最高4096维自定义 | 曾MTEB多语言榜第一，长文本、多语言与代码能力强 | 高精度中英文RAG、长文档分析、代码检索 |
|
||||
| Qwen/Qwen2-Embedding-4B | 4B参数 | 性能与效率平衡 | 大规模生产级RAG系统，性价比高 |
|
||||
| Qwen/Qwen2-Embedding-0.6B | 0.6B | 适用于边缘端 | 资源不够的场景，需要速度优先的场景 |
|
||||
| BAAI/bge-m3 | 支持混合检索（密集+稀疏+多向量） | 在MIRACL等跨语言基准领先 | 需要混合检索策略的复杂多语言场景 |
|
||||
| BAAI/bge-large-zh-v1.5 | Large规模 | 中文RAG的稳定基线，社区验证充分 | 纯中文且文档较短、追求稳定性的项目 |
|
||||
| 智谱AI Embedding-3 | 闭源云端API | 支持自定义维度（256-2048维） | 注重中文且偏好云端API服务的应用 |
|
||||
|
||||
### 5.1.2 Rerank model
|
||||
|
||||
在 RAG 系统中，Rerank 模型的作用是对初步检索结果进行精细化重排序。它接收用户查询和候选文档作为输入，为每对（查询-文档）计算精确的相关性分数，分数越高表示文档与查询的匹配度越好。因此，在 Embedding 召回的基础上引入 Rerank 模型，是提升 RAG 系统检索精度的关键一步。
|
||||
|
||||
在选择 Embedding 模型时，我们可以用 MTEB 这样的 benchmark。而对于 Rerank 模型我们可以参考 Agentset 的 [Reranker Leaderboard](https://agentset.ai/rerankers)，该网站针对 RAG 场景下的重排能力做了系统测试。
|
||||
|
||||
| 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 |
|
||||
| [Cohere Rerank 4 Pro](https://agentset.ai/rerankers/cohere-rerank-4-pro) | 1627 | 0.219 | 614 | $0.05 | Proprietary |
|
||||
| [Contextual AI Rerank v2 Instruct](https://agentset.ai/rerankers/contextual-ai-rerank-v2-instruct) | 1461 | 0.23 | 3333 | $0.05 | cc-by-nc-4.0 |
|
||||
| [Jina Reranker v2 Base Multilingual](https://agentset.ai/rerankers/jina-reranker-v2-base-multilingual) | 1306 | 0.193 | 746 | $0.05 | cc-by-nc-4.0 |
|
||||
| [Voyage AI Rerank 2.5](https://agentset.ai/rerankers/voyage-ai-rerank-25) | 1547 | 0.235 | 613 | $0.05 | Proprietary |
|
||||
| [Voyage AI Rerank 2.5 Lite](https://agentset.ai/rerankers/voyage-ai-rerank-25-lite) | 1528 | 0.226 | 616 | $0.02 | Proprietary |
|
||||
| [Zerank 1](https://agentset.ai/rerankers/zerank-1) | 1574 | 0.192 | 266 | $0.03 | cc-by-nc-4.0 |
|
||||
| [Zerank 1 Small](https://agentset.ai/rerankers/zerank-1-small) | 1541 | 0.202 | 248 | $0.03 | Apache 2.0 |
|
||||
| [Zerank 2](https://agentset.ai/rerankers/zerank-2) | 1644 | 0.195 | 265 | $0.03 | cc-by-nc-4.0 |
|
||||
|
||||
在评估 Rerank 模型性能时，Agentset 基准测试采用以下流程：首先依据向量数据库 FAISS 从大规模文档库中检索出与查询最相关的前 50 个候选结果，随后由待评估的 Rerank 模型对这 50 个文档进行重新排序。评估过程同时关注排序质量和推理延迟两个关键维度。实际应用场景中，仅追求高精度而忽视响应速度将损害用户体验，而仅追求速度却牺牲排序质量则会导致结果实用性下降。
|
||||
|
||||
为进一步对比模型能力，Agentset 基准测试额外引入 ELO 评分机制：针对每次查询，会以 GPT-5 作为客观 “裁判”，对两个不同 Rerank 模型输出的排序结果展开成对比较，核心判定标准是哪个模型能将真正相关的文档排列得更合理、更靠前。经过海量查询的持续对比，获胜频率更高的模型将获得更高的 ELO 分数，从而直观体现模型综合性能差异。
|
||||
|
||||
在此基础上，基准测试还设计了两组互补性指标，用于对模型进行多维度综合评估：
|
||||
|
||||
* nDCG@5/10：聚焦排序精准度，重点衡量相关文档是否被合理置于结果前列，直接反映 “排得准” 的能力；
|
||||
* Recall@5/10：侧重结果覆盖面，核心评估系统能否识别出所有与查询相关的文档，对应 “找得全” 的能力。
|
||||
|
||||
这两组指标相辅相成，共同构建起对 Rerank 模型的完整评估体系，确保评估结果更具全面性与参考价值。
|
||||
|
||||
但在实际使用中，我们不一定需要仅是参考 LeaderBoard 进行模型选型，除去刷榜的因素，主要还是因为工业上的好用和分数高不一定是一回事，我们可以根据各个云服务厂商推荐的 Rerank 模型进行选择（比如大模型厂商的默认 Rerank API，或可以尝试 Qwen 对应的 Rerank 模型，在当前 2025 年的情况下作为多参数支持的 Rerank 模型效果尚可。）
|
||||
|
||||
### 5.1.3 LLM
|
||||
|
||||
经过Embedding模型的语义检索和Rerank模型的精准筛选后，相关文档片段会与用户的原始问题一同被整合进prompt，最终由LLM完成阅读理解、信息整合与自然语言生成，向用户输出连贯、准确且符合上下文的答案。
|
||||
|
||||
在实现层面，RAG 中的 LLM 使用方式主要分为两类：
|
||||
|
||||
1. 私有化部署的大模型。适用于注重数据隐私、成本可控或需要深度定制的场景。当前主流开源LLM如Qwen系列、Llama系列、GLM系列等在RAG任务中表现优异。以Qwen2.5为例，7B或14B参数版本在保持较小资源占用的同时，展现出良好的指令遵循能力和中文理解能力，特别适合企业级RAG应用的本地化部署。KIMI、Minimax、DeepSeek等模型也在不同语言和领域展现出各自优势，可根据具体业务需求灵活选型。
|
||||
2. 作为云端API服务的大模型。适合追求快速上线、弹性扩展和持续模型迭代的场景。主流提供商如OpenAI（GPT-4系列）、Anthropic（Claude系列）、Google（Gemini系列）以及国内的阿里（通义千问）、智谱AI（GLM系列）等都提供稳定的API服务。这些模型普遍具备强大的语言理解和生成能力，能够高质量完成RAG场景下的答案合成任务。
|
||||
在选择云端模型时，需要关注几个关键点：回答质量是否准确流畅、价格是否合理、响应速度是否够快、上下文窗口是否足够大（能放下检索到的多个文档）。实际使用时，可以先拿几个候选模型做对比测试，看看哪个回答得更准确完整。如果对成本敏感，可以用"大小模型搭配"的方式：简单问题用便宜的小模型，复杂问题才调用贵的大模型，这样既省钱又保证效果。另外，大模型更新很快，建议定期测试新模型，及时替换表现更好的版本。
|
||||
|
||||
对于大语言模型在对话和问答场景下的综合能力评估，[LMSYS Chatbot Arena (LMArena) ](https://lmarena.ai/)提供了业界认可的黄金评测基准。该平台采用创新的"盲测对战"机制——人类评估者在不知晓模型身份的情况下，对两个匿名模型针对同一提示的回复进行质量比较，通过大量这样的两两对比为各模型排名。
|
||||
|
||||
以下是竞技场排名的示例（截止至 2025 年 12 月 15 日）
|
||||
|
||||
| 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 |
|
||||
| 4 | [claude-opus-4-5-20251101](https://www.anthropic.com/news/claude-opus-4-5) | 1467 | 10,659 | Anthropic | Proprietary |
|
||||
| 5 | [grok-4.1](https://x.ai/news/grok-4-1) | 1465 | 16,501 | xAI | Proprietary |
|
||||
| 6 | [gpt-5.1-high](https://openai.com/index/gpt-5-1/) | 1457 | 13,953 | OpenAI | Proprietary |
|
||||
| 7 | [gemini-2.5-pro](http://aistudio.google.com/app/prompts/new_chat?model=gemini-2.5-pro) | 1451 | 76,975 | Google | Proprietary |
|
||||
| 8 | [claude-sonnet-4-5-20250929-thinking-32k](https://www.anthropic.com/news/claude-sonnet-4-5) | 1450 | 28,019 | Anthropic | Proprietary |
|
||||
| 9 | [claude-opus-4-1-20250805-thinking-16k](https://www.anthropic.com/news/claude-opus-4-1) | 1448 | 43,836 | Anthropic | Proprietary |
|
||||
| 10 | [claude-sonnet-4-5-20250929](https://www.anthropic.com/news/claude-sonnet-4-5) | 1445 | 23,185 | Anthropic | Proprietary |
|
||||
|
||||
LMArena的独特价值在于其评估方式更贴近真实用户体验，而非单纯依赖自动化指标。排行榜不仅展示整体排名，还细分为不同能力维度（如推理能力、创造能力、多语言支持等），帮助开发者根据实际应用场景选择最适合的模型。截至2025年，该平台已累计超过100万次人类评估，涵盖50+主流开源与闭源模型，成为LLM选型的重要参考。
|
||||
|
||||
访问LMArena官网可查看实时排行榜、详细能力分析和模型间的直接对比数据。但在实际选型中，建议将LMArena排名作为初步筛选依据，再结合企业特定数据进行A/B测试。特别是在专业领域（如医疗、法律、金融），通用榜单排名与实际表现可能存在较大差异，针对性测试尤为重要。
|
||||
|
||||
对于 LLM 选型的最佳实践是构建一个小型但代表性的测试集，包含20-30个典型业务问题，对候选模型进行端到端的RAG流程评估，而非仅评估LLM单点性能，比如使用推理模型还是非推理模型，使用什么参数的模型能平衡 RAG 效果和速度；这些都需要在实际的使用过程中测试得到最佳结论。
|
||||
|
||||
## 5.2 运行框架
|
||||
|
||||
在实际工程实践中，通常不需要从零开始构建整个 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 应用。
|
||||
|
||||
如果团队技术储备有限、追求快速上线，可优先考虑 Dify 、Coze 或 FastGPT 等低代码平台；如果需要深度定制检索框架、对接特殊数据源或优化性能细节，LlamaIndex 和 LangChain 提供了更大的灵活性。实际项目中，也可以采用"混合方案"：用低代码平台快速验证可行性，再用代码框架实现生产级部署和性能优化。此外，这些框架大多支持主流 Embedding、Rerank 和 LLM 模型的快速接入，可以基于前文提到的模型选型标准灵活组合最后使用的模型型号。
|
||||
|
||||
## 5.3 效果评测
|
||||
|
||||
企业在 RAG 系统落地过程中，最大的挑战往往不是构建而是调优，对大型企业来说。生产级的大型 RAG 系统需要可监测可量化评估效果。RAG 涉及检索和生成两个非确定性环节，传统的软件测试方法不再适用，建立科学的评测体系（RAG Evaluation）至关重要，我们需要了解如何对 RAG 的效果进行系统化的评估。
|
||||
|
||||
### 5.3.1 入门示例：基于 LLM 的 RAG 效果评测
|
||||
|
||||
为帮助大家快速建立对 RAG 效果评测的直观理解，本节将以一个基于 LLM 的 RAG 效果自动化评测流程为例进行说明。该方案核心是 “LLM-as-a-judge”，即利用大模型本身作为裁判，来量化评估 RAG 系统的输出质量 https://huggingface.co/learn/cookbook/rag_evaluation。
|
||||
|
||||
具体而言，该流程通常包含三个关键步骤：
|
||||
|
||||
* 首先合成评测数据集，我们需要从知识库中采样文档，并指令 LLM 生成与之对应的、高质量的“问题-参考答案”对，再经过相关性、事实 groundedness 等过滤，形成基准测试集；
|
||||
* 其次，运行 RAG 系统并收集答案，让待评估的系统处理测试集中的每个问题，得到其生成的答案；
|
||||
* 最后，进行自动化判分，调用另一个作为“裁判”的 LLM，将系统生成的答案与参考答案进行对比，从准确性、完整性等维度给出量化评分。
|
||||
|
||||
可以用一个简单的例子展示其过程：
|
||||
|
||||
1. 出题（合成评测集）：我们有一份知识库，例如一段产品说明书：“本设备支持无线充电，电池容量为5000mAh。” 我们让一个大模型（如GPT-4）扮演“出题官”，根据这段文本自动生成一道测试题，例如：“这个设备的电池容量是多少？” 并记录标准答案：“5000mAh”。这就构成了一条评测数据。
|
||||
2. 答题（运行RAG系统）：将这道题输入到待评测的 RAG 系统中。系统会从知识库检索相关信息，并生成一个答案。假设它回答：“该设备电池容量是5000mAh。”
|
||||
3. 批改（LLM-as-a-Judge）：我们请另一个大模型（如Claude 3）扮演“批改老师”。将“问题”、“RAG生成的答案”和“标准答案”一起交给它，并指令：“请判断生成的答案是否正确，只需输出‘正确’或‘错误’。” “批改老师”经过对比，输出：“正确”。
|
||||
|
||||
通过自动化批量测试，我们能够得到RAG系统的准确率等具体指标。这就形成了一个“评测、优化、再评测”的实用循环：先看数据找出问题，再调整检索方法或优化模型，然后重新测试验证效果。系统就在这样一次次的迭代中，实现持续改进和性能提升。
|
||||
|
||||
你已经知道了评测在 RAG 中意味着什么，接下来我们将聚焦 RAG 评测的核心组成部分：常见的评测指标（如检索阶段的 Recall@K、生成阶段的 Faithfulness）、主流评测框架（如 RAGAS、ARES）与基准数据集（如 WikiEval、MedRAG）。鉴于这些内容覆盖面广、细节庞杂，此处暂先进行概览性介绍，帮助你建立整体认知框架。
|
||||
|
||||
若你需要深入掌握具体细节（如指标的数学计算逻辑、框架的实操部署步骤、不同基准数据集的适用场景等），建议参考以下两篇 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），从 “评测目标、数据集、指标” 三维度拆解评测逻辑，同时对比了不同基准的优劣，为实践提供了清晰指引。
|
||||
|
||||
### 5.3.2 评测指标
|
||||
|
||||
RAG系统的评估本质上围绕两个核心问题：检索模块能否准确找到相关资料，生成模块能否基于这些资料给出高质量回答。因此，评测体系相应分为检索效果评估、生成质量评估两大模块，并辅以LLM裁判进行综合评分。下面我们逐一展开。
|
||||
|
||||
#### 检索效果评估：召回准确性与排序质量
|
||||
|
||||
检索模块是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的调和平均,在两者间寻求平衡。
|
||||
|
||||
这组指标适合快速发现召回阶段的基础问题,比如向量化模型是否有效、检索策略是否合理、Query改写是否到位等。如果Recall很低,说明相关文档根本没被找到;如果Precision很低,说明检索噪声太大。
|
||||
|
||||
**排序质量指标**
|
||||
|
||||
找到相关文档只是第一步,更重要的是把最相关的文档排在前面。这就需要关注排序质量的指标：MRR、NDCG@K和MAP。
|
||||
|
||||
* **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,说明相关文档虽然被找到了但都埋在后面,这时就需要优化重排序策略,比如引入交叉编码器或调整多路召回的权重分配。
|
||||
|
||||
必要时,还可以补充 Coverage 指标来监控知识库覆盖情况,发现系统性的召回盲区。比如某类专业术语相关的问题始终召回效果不佳,就要考虑是否需要针对性地优化该领域的文档切分或向量化方式。
|
||||
|
||||
#### 生成质量评估：准确性与事实忠实度
|
||||
|
||||
检索为生成提供了"原材料",接下来要评估的是：基于这些材料,生成模块能否给出高质量的答案?生成质量评估的核心维度有两个：答案是否准确,是否忠于检索到的证据。
|
||||
|
||||
**精确匹配与文本相似度**
|
||||
|
||||
最直接的评估方式是 **EM(Exact Match)** ,要求生成答案与参考答案完全一致。这个指标适合答案唯一、形式固定的场景,比如"成立日期是什么时候?""总部在哪里?"这类事实性问答。但EM过于严格,同样正确的"2020年1月1日"和"2020-01-01"会被判为不匹配。
|
||||
|
||||
因此,更常用的是基于n-gram重叠的相似度指标： **ROUGE** **、** **BLEU** **、METEOR** 。它们通过计算生成内容与参考答案的词汇重叠程度来打分。其中,ROUGE-L关注最长公共子序列,对答案的流畅性更敏感;BLEU源自机器翻译领域,注重精确匹配;METEOR则加入了同义词和词干的考量。这些指标的优势是计算简单、易于理解,但也有明显局限——它们只看表面词汇匹配,对语义理解不够深入。
|
||||
|
||||
为了弥补这一不足,我们可以引入 **BertScore** 或直接的 **向量相似度** 。它们利用预训练模型的向量表示来计算语义相似度,更能容忍表述差异。比如"这款产品很受欢迎"和"该设备广受好评"在词汇上几乎没有重叠,但向量相似度会很高。这对于需要改写、总结、解释的生成任务特别有效。
|
||||
|
||||
**事实忠实度与幻觉检测**
|
||||
|
||||
对于RAG系统而言,仅仅评估答案与参考标准的相似度还不够,更关键的问题是：生成的答案是否基于检索到的文档,有没有"无中生有"的幻觉?
|
||||
|
||||
这就需要专门的 Hallucination(幻觉率) 和 Faithfulness(忠实度) 指标。具体做法是让另一个LLM扮演"事实核查员",逐句检查生成答案,判断每句话是否能在检索文档中找到依据。比如,检索文档说"产品重量为500克",但生成答案写"该产品轻巧便携,仅重300克",这就是一个典型的幻觉。通过统计有依据的语句占比,我们可以量化系统的忠实度。
|
||||
|
||||
这个指标对监控事实性错误至关重要,特别是在医疗、法律、金融等对准确性要求极高的领域。实践中,许多企业会设置幻觉率阈值作为上线标准,比如要求准确度必须达到95%以上。
|
||||
|
||||
#### LLM裁判：多维度综合评分
|
||||
|
||||
前面介绍的指标各有侧重,但都存在一定局限性：自动化指标往往只看表面特征,难以把握语义深层含义和整体质量。这时,**LLM-as-a-Judge** 机制就显得尤为重要。
|
||||
|
||||
具体做法是:将问题、检索文档、系统回答、参考答案一并输入一个独立的大模型(通常选择能力较强的模型如GPT-4或Claude),让它按多个维度进行综合评分：
|
||||
|
||||
* **问题相关性** ：答案是否真正回应了用户问题,有没有答非所问?
|
||||
* **信息完整性** ：该涵盖的要点是否都说到了,有没有遗漏关键信息?
|
||||
* **事实忠实性** ：答案是否出现了检索文档中不存在的内容,有没有幻觉?
|
||||
* **整体正确性** ：与参考答案相比,生成答案的质量如何?
|
||||
|
||||
LLM裁判的优势在于能进行更接近人类的整体性判断——它可以理解上下文、把握语义、识别逻辑,甚至能发现一些自动化指标捕捉不到的细微问题,比如语气不当、逻辑矛盾、表述含糊等。当然,裁判本身也需要精心设计prompt,并用人工标注样本进行校准,确保评分标准的一致性和可靠性。
|
||||
|
||||
#### 构建实用的评测组合
|
||||
|
||||
面对如此多的评测指标,企业在落地时往往会感到困惑：该选哪些指标?如何组合使用?
|
||||
|
||||
一个务实的建议是 **从精简组合开始,逐步完善** ：
|
||||
|
||||
* **检索评估** ：采用 Recall@K + MRR@K 的核心组合,快速把握召回覆盖和排序质量
|
||||
* **生成评估** ：根据任务特点,从 EM、ROUGE-L、BertScore 中选择一到两个作为基线
|
||||
* **综合评估** ：引入 LLM裁判,重点关注相关性、完整性、忠实性三个维度
|
||||
|
||||
在此基础上,采用"评测→发现问题→调整策略→再评测"的循环迭代。比如,发现召回率不错但MRR很低,就重点优化重排序;发现幻觉率偏高,就加强对检索文档的忠实度约束;发现某些类型的问题回答质量不好,就针对性地补充细分指标。
|
||||
|
||||
这种渐进式构建方式既能让团队快速起步,建立对系统效果的基本认知,又能随着理解的深入逐步完善评估体系,最终形成一套适合自己业务场景的评测方案。
|
||||
|
||||
### 5.3.3 评测框架
|
||||
|
||||
随着RAG技术的快速发展,学术界和工业界涌现出了大量优秀的评测框架,它们不仅封装了常用的评测指标,还提供了标准化的数据集、基准测试和端到端的评估流程。本节将系统梳理当前主流的RAG评测框架,帮助你快速选择适合自己场景的评测工具。
|
||||
|
||||
#### **评测框架的分类体系**
|
||||
|
||||
根据评测目标和使用场景,我们可以将RAG评测框架分为三大类：研究型框架、基准测试框架和工具型框架。
|
||||
|
||||
**研究型框架**主要服务于学术研究和前沿探索,特点是评测维度细致、方法创新性强。代表性的如FiD-Light和Diversity Reranker,它们专注于检索阶段的细粒度评估,前者关注召回的延迟性(Latency),后者强调结果的多样性(Diversity)。这类框架通常会深入到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评分体系
|
||||
|
||||
进入2024年后,评测框架呈现出明显的专业化和细分化趋势。医疗领域有MedRAG,法律领域有LegalBench-RAG,金融领域有相关的domain-specific框架。这些领域框架不仅提供了专业数据集,还针对行业特点设计了定制化的评测指标,比如医疗场景特别关注准确性(Accuracy),法律场景强调文档级精确度(Doc-level Precision)和引用相关性(Citation Relevance)。
|
||||
|
||||
**工具型框架**则侧重于工程实践,提供了易用的评测工具和集成方案。TruEra RAG Triad、LangChain Benchmarks、RECALL等都属于这一类。它们通常与主流的RAG开发框架深度集成,支持快速接入现有系统,有些还提供了可视化的评测报告和监控面板。
|
||||
|
||||
上述我们介绍了多种不同的 RAG 评测框架，但在具体实战中该如何选择？不妨先选取 GitHub 星标数量较多的几款进行初步测试；而当企业面临丰富的框架选择、需要落地决策时，可从以下几方面着手。
|
||||
|
||||
* 快速上手需求：若需快速搭建基线评测，可选择 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 等工具也在持续迭代中，你可综合自身需求和对应工具的口碑进一步选用。
|
||||
|
||||
### 5.3.4 评测基准
|
||||
|
||||
评测基准的重要性在实践中常常被低估。许多团队在搭建RAG系统时，往往仅依靠少量人工编写的测试问题便匆忙开始评估，导致上线后的实际效果与测试阶段的表现差距显著。这一问题的根源在于，缺乏具有代表性和系统性的评测数据，难以真实反映复杂多变的业务场景。
|
||||
|
||||
一个能够有效支撑系统迭代的评测基准，通常具备三个核心特征。首先是代表性，测试数据需要全面覆盖真实业务中的各种场景，包括高频常见问题、复杂边界情况以及异常输入等；其次是标准化，问题和答案的格式、难度系数、评分标准需要统一规范，确保评测结果具有可比性和可重复性；最后是可演化性，基准应能随着系统能力提升和业务需求变化而持续更新，避免因固化的“应试”数据导致评测失真。
|
||||
|
||||
对于大多数企业而言，由于业务场景存在独特性，最终往往需要构建自己的评测数据集。
|
||||
|
||||
* 构建过程可以从业务日志中提取真实用户问题入手，并依据类型、频率和难度进行分层采样，以保证数据的代表性。对于简单问题可由领域专家直接标注,复杂问题则可先用高质量LLM生成候选答案,再由专家审核修改,这种"机器生成+人工校准"的方式能显著降低标注成本。
|
||||
* 除答案本身,标注相关文档、答案类型、难度等级等元信息,为后续细分析提供支持。建立标注规范,进行多人交叉验证,计算标注一致性(如Kappa系数),确保数据质量。
|
||||
* 定期从线上反馈中补充新的测试用例,尤其是系统回答不好的问题,让评测数据与系统能力同步演进。这种持续迭代的机制能让评测基准始终保持对业务场景的敏感度和有效性。
|
||||
|
||||
当然，如果团队资源有限或希望快速建立基线，参考业界成熟的公开评测基准也是一个可行的起点。截至2025年，已有诸多涵盖通用领域和垂直行业的基准可供选择（见图表）。
|
||||
|
||||
|
||||
|
||||
在选择时，应首先明确评测目的：是建立能力基线，还是为上线做最终验证？其次，需评估基准数据是否覆盖了所关心的场景、问题类型和难度。对于新闻、金融等时效性强的场景，必须考察基准是否包含实时数据测试；而对于历史知识处理，静态基准可能已足够。最后，还需权衡标注成本，是直接采用已完整标注的基准，还是使用原始数据自行标注。
|
||||
|
||||
将自建数据与公开基准结合使用，既能确保评测贴近业务实际，又能借助公共标准进行横向比对，是构建稳健评测体系的务实路径。
|
||||
|
||||
# 6. 深度研究：从比赛与开源教程中学习（Optional）
|
||||
|
||||
前面介绍的RAG系统原理和基础实现，虽然能帮助你快速搭建起一个可用的原型，但距离真正解决生产环境中的复杂问题还有不小的距离。如果你想深入理解更落地、更有实战价值的RAG技术，参考各大比赛的获奖方案和优质开源教程是最高效的学习路径，这些方案往往集中了优秀团队在真实场景下反复尝试后的最佳实践。
|
||||
|
||||
但需要强调的是，本节列举的案例并非全部，而是挑选了几个有代表性的方案。当你在实践中遇到特定问题时，建议采用这样的学习策略：先根据问题类型（如"PDF解析"、"多模态检索"、"低延迟优化"等关键词）查找相关竞赛，再深入研究获奖队伍的技术报告或开源代码，往往能找到直接可用的解决思路。
|
||||
|
||||
## 6.1 语义缓存：优化高频查询场景
|
||||
|
||||
Hugging Face提供了一个基于Chroma向量数据库的语义缓存实现方案，该教程的地址为：
|
||||
|
||||
[https://huggingface.co/learn/cookbook/semantic_cache_chroma_vector_database](https://huggingface.co/learn/cookbook/semantic_cache_chroma_vector_database)
|
||||
|
||||
|
||||
|
||||
背景：大多数教程搭建的RAG系统只适合单用户测试，当系统部署到生产环境后，面对几十到几千次的重复查询（比如客服场景中用户反复询问"如何退款"），每次都要执行向量数据库检索和LLM调用，响应时间会明显增加，成本也会快速上升。通过引入语义缓存层，可以在保证答案质量的前提下，大幅减少对原始数据源的访问压力。
|
||||
|
||||
该方案采用了双层检索架构。基础层使用Chroma向量数据库存储原始知识库（以MedQuad医疗问答数据集为例），为每条数据添加唯一ID方便精确引用。缓存层则基于FAISS构建，选择FlatL2索引来处理小数据集和高维向量。语义缓存被放在用户查询与Chroma之间，而不是缓存LLM的最终回答——这个设计很重要，因为直接缓存回答会导致用户的个性化要求（如"用简单语言解释"）失效。
|
||||
|
||||
缓存系统使用SentenceTransformer的all-mpnet-base-v2模型生成查询向量，通过欧氏距离（设定阈值为0.35）来判断查询是否相似。当缓存满了（max_response参数控制容量）时，采用先进先出策略删除最早的条目。为了支持跨会话使用，缓存数据会保存到JSON文件中。
|
||||
|
||||
在小规模测试中，首次查询"How do vaccines work?"从Chroma获取结果耗时0.057秒，而相似查询"Briefly explain me what is a Sydenham chorea."从缓存获取仅需0.016秒，检索时间减半。在大规模生产环境中，这个方案可以实现90%-95%的性能优化，有效降低了向量数据库的访问压力和API调用成本。
|
||||
|
||||
## 6.2 非结构化数据处理：统一多格式文档解析
|
||||
|
||||
Hugging Face的另一个教程展示了如何使用Unstructured库构建完整的非结构化数据处理流程，教程地址为：
|
||||
|
||||
[https://huggingface.co/learn/cookbook/rag_with_unstructured_data](https://huggingface.co/learn/cookbook/rag_with_unstructured_data)
|
||||
|
||||
|
||||
|
||||
背景：企业场景中的知识往往分散在PDF、PowerPoint、EPUB、HTML等多种格式中，传统的数据预处理方法要么只能处理单一格式（比如只支持PDF），要么在格式转换过程中丢失关键信息（特别是表格、标题层级等结构化内容），导致RAG系统无法准确理解和检索这些信息。
|
||||
|
||||
该方案首先下载多格式测试文档作为示例，包括加拿大环境部农药手册PDF（包含大量表格数据）、佛罗里达大学柑橘IPM PowerPoint（包含图表和多层级标题）等真实文档。然后使用Unstructured库的Local Runner完成解析。配置分为三个部分：ProcessorConfig指定输出目录和并行进程数（2个进程），PartitionConfig可选择API分区模式（需要Unstructured密钥，OCR效果更好，特别适合扫描版PDF），SimpleLocalConfig定义文档输入路径。解析后的文档会转换为JSON格式，包含正文、标题、表格等元素类型。
|
||||
|
||||
系统使用chunk_by_title方法进行分块，设置最大字符数为512，并将200字符以下的连续片段合并以保持语义完整性。在转换为LangChain Document格式时，会过滤掉复杂的元数据字段以适配Chroma向量数据库。向量化阶段采用BAAI/bge-base-en-v1.5嵌入模型，结合4bit量化的Llama-3-8B-Instruct模型和LangChain的RetrievalQA链构建完整的RAG系统。
|
||||
|
||||
系统能够准确处理多格式文档。测试"Are aphids a pest?"等问题时，可以从解析后的文档中提取蚜虫危害、吸引蚂蚁等关键信息，生成符合需求的回答。这个方案成功实现了从非结构化数据到RAG可用数据的完整转化，特别适合需要处理多种文档格式的企业知识库场景。
|
||||
|
||||
## 6.3 企业级文档问答：高精准可追溯的RAG实现
|
||||
|
||||
Enterprise RAG Challenge的冠军方案展示了如何在严格的时间和精度要求下构建生产级RAG系统，相关技术文章地址为：
|
||||
|
||||
[https://abdullin.com/ilya/how-to-build-best-rag/](https://abdullin.com/ilya/how-to-build-best-rag/)
|
||||
|
||||
[https://hustyichi.github.io/2025/07/03/rag-complete/](https://hustyichi.github.io/2025/07/03/rag-complete/)
|
||||
|
||||
背景：参赛者需要在2.5小时内完成100份真实企业年度报告PDF的解析，这些报告每份最多1000页，包含复杂的财务表格、多栏布局、图表等内容。解析完成后，系统需要回答100个精确的业务问题，这些问题要求明确的答案类型（比如Yes/No判断、公司名称、具体数值指标、高管职位名称等），并且必须给出答案来源的页码引用，以便业务人员验证。整个过程模拟的是投资分析师或财务审计人员的实际工作场景。
|
||||
|
||||
冠军团队选择IBM开源的Docling作为PDF解析工具，因为它在处理复杂表格（比如跨页表格、嵌套表格）和多列文本方面表现最好。团队对Docling代码进行了改进，使其生成包含元数据的JSON和Markdown+HTML格式，特别修复了表格结构的解析问题（比如单元格合并、表头识别等）。为了加速处理，团队租用RTX 4090 GPU，在40分钟内完成了100份报告的解析。
|
||||
|
||||
文本分块采用300 token长度，重叠50 token，使用递归分割策略保持语义完整。为了避免跨公司信息混淆（比如查询A公司CEO时检索到B公司的信息），为每个公司单独构建FAISS向量库，采用IndexFlatIP索引（不压缩以保证精度）。检索阶段采用三步走策略：首先通过向量检索找到Top30文本块，然后提取这些块所在的父页面并去重（因为多个块可能来自同一页），最后使用GPT-4o-mini对页面进行重新排序。向量检索分数与LLM重排序分数按0.3:0.7的权重混合。
|
||||
|
||||
生成阶段根据答案类型（数字/布尔/字符串等）使用不同的prompt模板。对于数字类问题（比如"2023年营收是多少"），设计了5步分析流程来确保指标匹配的准确性：识别问题中的指标类型、在文档中定位相关表格、提取数值、验证单位一致性、交叉验证。系统输出采用结构化格式，包含分析过程、相关页码等字段，确保答案可追溯。对于涉及多公司比较的问题（比如"哪家公司营收最高"），会拆分为单公司子查询后再合并结果。
|
||||
|
||||
该方案在竞赛中获得双奖项及排行榜第一。值得注意的是，即使使用小模型（如Llama 8B）也能超过80%的参与者，使用Llama 3.3 70B时仅比GPT-4o-mini稍差一点，成功实现了准确性、效率与成本的平衡。
|
||||
|
||||
## 6.4 AIOps场景：图文混合数据的智能处理
|
||||
|
||||
AIOps RAG竞赛的EasyRAG项目专注于运维场景下的问答任务，技术文章地址为：
|
||||
|
||||
[http://blog.csdn.net/hustyichi/article/details/143323746](http://blog.csdn.net/hustyichi/article/details/143323746)
|
||||
|
||||
|
||||
|
||||
背景：运维工程师日常工作中需要查阅大量技术文档，这些文档不仅包含文字说明，还包含监控图表、系统架构图、性能曲线等图片信息。比如当系统出现性能问题时，工程师需要快速查询"CPU使用率超过80%时应该如何处理"，答案可能分散在文字说明和监控图表中。传统RAG系统只能处理文字，无法理解图表中的趋势和数值，导致答案不完整。该项目最终获得初赛第一、复赛第二的成绩。
|
||||
|
||||
索引阶段使用改进过的SentenceSplitter（修复了原版块大小计算问题），按1024 token分块，重叠200 token。关键创新在于为每个文本块添加知识库路径、文件路径等元信息，这个改进使召回率提升了2%。对于图片数据，先使用PaddleOCR提取图片中的文字（比如图表的标题、坐标轴标签），再调用GLM-4V-9B多模态模型生成图片的自然语言描述（比如"该折线图显示CPU使用率在下午3点达到峰值90%"），将文字和描述一起入库，实现了图文信息的统一检索。
|
||||
|
||||
检索阶段采用"双路BM25+向量检索"策略进行广泛召回。BM25包含文档块检索（召回192条）和路径检索（通过文件路径过滤无关文档，比如只检索运维手册而不检索开发文档），使用哈工大停用词表进行去噪。向量检索使用gte-Qwen2-7B-instruct模型，召回288条候选结果。重排序阶段使用bge-reranker-v2-minicpm-layerwise模型，经过测试发现28层配置效果最好。
|
||||
|
||||
答案生成采用两步策略——先基于Top6文档生成初步结果（覆盖多个相关知识点），再结合Top1最相关文档进行二次优化（突出最核心的答案）。这个设计确保了答案既有足够的信息覆盖面，又能突出最核心的内容。
|
||||
|
||||
为了应对长文本场景（比如一份完整的运维手册可能有几百页），系统实现了基于BM25的上下文压缩方法。该方法将文档拆分为句子级别，计算每个句子与查询的相似度，然后按比例拼接高相关句子。实验表明，在50%压缩率下，该方法耗时仅7.7秒，准确率达86.48%，优于LLMLingua等现有压缩工具。
|
||||
|
||||
相比基础方案，加入元信息和答案二次优化后，系统准确性分别都提升了2%。BM25压缩方法在保证效率的同时保持了较高的准确性，很好地适配了AIOps场景下图文数据处理和实时响应的需求。
|
||||
|
||||
## 6.5 多源数据融合：结构化与非结构化知识的协同
|
||||
|
||||
KDD Cup 2024 Meta RAG挑战赛的冠军方案展示了如何整合非结构化Web数据和结构化知识图谱，技术文章地址为：
|
||||
|
||||
[https://blog.csdn.net/m0_59164520/article/details/143694213](https://blog.csdn.net/m0_59164520/article/details/143694213)
|
||||
|
||||
https://arxiv.org/pdf/2410.00005
|
||||
|
||||
|
||||
|
||||
背景：任务1要求基于5个网页做检索摘要，比如用户搜索"星际穿越导演是谁"，系统需要从给定的网页中提取答案。任务2在任务1基础上增加了Mock API（模拟访问结构化知识图谱），系统可以调用API查询电影数据库、人物关系等结构化信息。任务3进一步扩大难度，基于50个网页与Mock API处理复杂查询，比如"哪些由诺兰导演的电影票房超过5亿美元"，这需要同时查询知识图谱（导演作品关系）和网页（票房数据）。每个查询需在30秒内完成，核心目标是提升多源数据整合的准确性并减少幻觉。
|
||||
|
||||
北大db3团队针对任务1设计了精细化的Web数据处理流程。使用BeautifulSoup提取网页文本，ParentDocumentRetriever管理父子块关系（子块200 token用于检索、父块500-2000 token用于生成），确保检索准确性和生成完整性。嵌入模型选用bge-base-en-v1.5，向量库使用Chroma，重排序采用bge-reranker-v2-m3。团队还补充了电影、金融等领域的公开数据（比如IMDB电影数据、上市公司财报），转换为规范格式后入库。模型层面使用LoRA微调Llama-3-8B-instruct，训练数据包括无效问题标注（比如"今天天气怎么样"这类超出知识库范围的问题）、正确答案等。
|
||||
|
||||
任务2-3的关键创新在于优先使用知识图谱。团队设计了规范化的API调用机制，包括get_person（查询人物信息）、get_movie（查询电影信息）等接口，支持条件过滤（比如cmp操作符筛选票房>5亿的电影）和排序（按票房降序）。API调用生成采用GPT-4初步标注后人工优化的方式进行微调。系统执行时先调用知识图谱API，只有在知识图谱结果无效（比如查询的电影不在数据库中）时才回退到Web检索，这个设计大幅提升了查询效率和答案准确性。
|
||||
|
||||
通过知识图谱优先策略和结构化输出格式，系统明显减少了LLM的幻觉现象。当知识图谱能提供确定性答案时（比如"诺兰出生年份"），直接输出不经过生成步骤；当需要从Web检索时（比如"诺兰最新访谈内容"），通过严格的文档引用和分步推理确保答案可验证。
|
||||
|
||||
该方案在三个任务中均获第一，得分分别达到28.4%、42.7%和47.8%，成功平衡了多源数据整合的准确性与实时性。这个案例的核心启示在于，对于包含结构化和非结构化数据的企业场景，应该根据数据特点设计不同的检索策略，优先使用确定性强的结构化数据，用非结构化数据作为补充。
|
||||
|
||||
深入分析这几个实践案例，我们可以总结出构建高质量RAG系统的几个共同原则：在架构设计上，应该根据业务场景选择合适的缓存、检索和生成策略；在数据处理上，需要针对不同格式和模态设计专门的解析和索引方案；在检索优化上，混合检索加重排序已成为标准配置；在答案生成上，分类型的prompt和结构化输出能明显提升准确性和可追溯性。
|
||||
|
||||
这些来自真实竞赛和开源项目的经验，为搭建更好的企业级RAG系统提供了宝贵的参考，你可以根据实际问题搜索对应的比赛，找到成熟现有方案进行尝试。
|
||||
|
||||
# 7. 广度探索：RAG 的未来演化（Optional）
|
||||
|
||||
在深入掌握了RAG的实战技巧与优化方法后，你已经能够在具体场景中有效提升系统性能。然而，要全面把握RAG技术，仅靠对局部的深入钻研还不够，我们还需拓展视野，从更广阔的维度理解其演进方向与扩展空间。
|
||||
|
||||
当前，RAG技术正在迅速突破传统基于文档分块的检索生成范式，朝着更多样化的方向发展。本节将重点探讨以下几个演进路径：从简单的分块检索转向对图数据结构的检索；融合图像、音频等多模态信息以增强RAG的检索能力；利用向量化技术优化长文档的分块处理策略；以及RAG如何逐步演化为智能体（Agent）系统。
|
||||
|
||||
## 7.1 Graph RAG：用关系网络重塑深度检索
|
||||
|
||||
相关研究：[https://arxiv.org/pdf/2410.05779](https://arxiv.org/pdf/2410.05779)， [https://arxiv.org/pdf/2502.11371](https://arxiv.org/pdf/2502.11371)， https://arxiv.org/pdf/2404.16130
|
||||
|
||||
|
||||
|
||||
传统RAG依靠寻找和问题相似的文本段落来工作，这就像在一堆材料里挑出看起来最相关的几段话。对于直接查找某个具体信息，这种方法很有效。但如果一个问题需要联系多份文档、结合不同线索才能回答，它的表现就会打折扣。
|
||||
|
||||
比如，医生可能想问：“根据这些病例和最新的治疗指南，如何评估某种药物对老年患者的好处和风险？”又或者，项目团队可能关心：“综合过去两年的需求文档、评审记录和线上问题报告，我们这个系统架构最常出问题的环节是什么？”这类问题的关键，不是找到某一句原话，而是要从各种分散的材料中，找出其中提到的人、事、物以及它们之间的联系，理清头绪，形成一幅完整的全景图。
|
||||
|
||||
Graph RAG的做法，就是先主动画出这幅全景图。系统会利用大模型从文本中识别出关键元素（比如人物、机构、功能模块、事件、数据等）以及它们之间的关系（比如谁导致了什么、什么依赖于什么、如何变化、有何矛盾等），从而构建一个随着资料增加而不断丰富的知识网络。接着，通过自动分组，把联系紧密的元素和关系归类到不同的主题下，并为每个主题提前生成一段概括性描述。这样，当用户提问时，系统不再仅仅是寻找字面上最相似的段落，而是会先在知识网络里找到与问题最相关的元素和局部结构，再顺着连接线扩展到相关的主题组，最后将这些分析路径、节点说明和对应的原始文本片段，一起交给大模型进行推理并组织答案。
|
||||
|
||||
在这样的框架下，Graph RAG和传统RAG形成了很好的分工与配合：传统RAG仍然擅长回答直接的、一步就能找到答案的细节问题；而Graph RAG则更像人在做研究或写报告时的思路——先梳理出整体结构和主题（构建网络与分组），再填充具体依据（引用原文），最后给出有逻辑、有条件限制的结论。已有的系统对比也显示，在需要联系多个信息点进行推理的任务中，Graph RAG通常能涵盖更关键的内容，提供更全面的视角；而根据问题的具体特点，灵活结合使用两种方法，整体效果往往比只使用其中一种更好。
|
||||
|
||||
## 7.2 Multimodal RAG：多模态 RAG
|
||||
|
||||
相关研究：https://arxiv.org/pdf/2502.08826
|
||||
|
||||
|
||||
|
||||
现实世界的数据从来不是单一文本。工程师排查服务器故障时，需要同时看温度监控曲线、设备面板截图和系统日志；医生做诊断时，需要把 CT / MRI 影像、检查报告和电子病历放在一起看。传统的文本 RAG 最多只能检索到“温度异常”“怀疑肺结节”这样的文字描述，却难以把这些描述与具体的曲线走势、影像病灶形态对应起来，更做不到用“图/音/视频”去反向检索相关文档和知识。
|
||||
|
||||
Multimodal RAG（多模态 RAG）解决的是这种“模态之间互相看不见”的问题。它的核心在于跨模态语义对齐：为图像、视频、音频、文本等分别配置合适的编码器（如 ViT/CLIP 编图像和视频帧，Whisper 编音频，BGE-M3 等编码文本），配合 OCR、ASR、版面分析等工具，把视觉和音频里的关键信息抽取出来，再通过模型把不同模态的表示映射到一个共享的语义空间中，构建统一的多模态索引。
|
||||
|
||||
在检索和生成阶段，不管用户是问“找一张显示 2023 年 Q3 销售峰值的图表”，还是上传一张产品草图或一段操作视频发起查询，系统都会先在这个统一空间里找到一批最相近的多模态内容，然后根据文本相似度、图像相似度等信号，筛掉明显无关的结果，保留几条最有用的证据。最后，把这些经过筛选的图、文、表格等，一并交给多模态大模型，由它综合不同模态的信息给出答案，并尽量标明信息来源，或在截图、文档中高亮相关位置。这样一来，相比只看文本的 RAG，系统既能利用更多模态的线索，又更容易减少幻觉，让答案更完整也更容易核实。
|
||||
|
||||
## 7.3 Late Chunking：为长文档保留完整上下文
|
||||
|
||||
相关介绍：https://jina.ai/news/late-chunking-in-long-context-embedding-models/
|
||||
|
||||
|
||||
|
||||
想象你正在阅读一篇关于柏林的维基百科文章，传统RAG系统会先将其切成独立段落再生成向量。当第一句提到"柏林是德国首都"后，后续段落中的"该城市"、"它的人口"等指代词就失去了与"柏林"的关联。此时若查询"柏林的人口是多少"，系统会因为"柏林"和"人口数据"从未在同一文本块出现而检索失败。这个问题在长文档场景更为严重：一份200页的保险合同中，"免赔额"的定义在第5页，具体适用条件在第30页，传统的固定长度切分（如每512 tokens一块）会将这些相关信息分散到40多个独立文本块中，实验数据显示这种割裂会导致语义相似度从0.85暴跌至0.71。
|
||||
|
||||
Late Chunking颠覆了"先切后编"的传统流程，改为"先编后切"：利用支持8192 tokens（约10页文本）的长上下文嵌入模型（如Jina Embeddings v2），首先将整个文档输入Transformer层，生成每个token的向量表示——此时每个token的嵌入已经"看到"了全文信息，捕获了跨段落的指代关系和概念关联。随后，再对这些已经全局感知的token向量进行分块平均池化（mean pooling），生成最终的块嵌入。这样生成的文本块不再是独立同分布的孤岛，而是"条件依赖"的上下文链：当处理"该城市有385万居民"这句话时，向量中已经包含了前文"柏林"的语义信息，使相似度从0.71提升至0.83。关键区别在于边界标记的使用时机：传统方法在预处理阶段就用句号、段落符切分文本，而Late Chunking仅在获得全局token嵌入后，才应用边界线索进行智能分块。
|
||||
|
||||
在BEIR基准测试的5个数据集上，Late Chunking全面超越传统切分方法。最显著的案例是NFCorpus数据集（平均文档长度1590字符），检索准确率从23.46%飙升至29.98%，相对提升27.8%；而在短文本场景（如Quora的62字符问题）两者表现相同，验证了一个关键规律：文档长度与Late Chunking的优势呈正相关。从技术对比表可见核心差异：传统切分在预处理阶段直接应用边界标记，产生独立同分布的块嵌入，上下文信息丢失；Late Chunking在获得token嵌入后才应用边界标记，产生条件依赖的块嵌入，由长上下文模型完整保留上下文信息。
|
||||
|
||||
该方法现已集成到Jina Embeddings v3 API中，虽然需要先编码整个长文档，推理时间增加10-20%，但在医疗病历（跨章节的诊断依据）、法律文档（定义与条款的交叉引用）、技术手册（概念解释分散在多个章节）等场景中，检索准确率的大幅提升远超过这点性能开销。Late Chunking不仅证明了8K+长上下文模型的实用价值——不是"过度设计"，而是实现高质量块嵌入的必要条件，更为RAG系统提供了一条摆脱滑动窗口、多次扫描等"hit-or-miss"启发式技巧、具有理论保证的优化路径，代表了从"先切后编"到"先编后切"的范式转变。
|
||||
|
||||
## 7.4 从 RAG 到 Agent 时代的 RAG
|
||||
|
||||
相关讨论：[https://ragflow.io/blog/rag-at-the-crossroads-mid-2025-reflections-on-ai-evolution](https://ragflow.io/blog/rag-at-the-crossroads-mid-2025-reflections-on-ai-evolution)， [https://arxiv.org/pdf/2501.09136](https://arxiv.org/pdf/2501.09136)， [https://www.letta.com/blog/rag-vs-agent-memory](https://www.letta.com/blog/rag-vs-agent-memory)， [https://www.linkedin.com/posts/richmondalake_100daysofagentmemory-rag-memorizz-activity-7348281860843577346-LM7Y/](https://www.linkedin.com/posts/richmondalake_100daysofagentmemory-rag-memorizz-activity-7348281860843577346-LM7Y/)， https://www.llamaindex.ai/blog/rag-is-dead-long-live-agentic-retrieval
|
||||
|
||||
RAG技术已从最初的检索增强生成工具，发展为构建智能体认知架构的关键部分。 传统RAG系统基于提问、检索、回答的简单模式，本质是被动接受查询，不具备主动行动的能力。为了突破这种被动性并处理更复杂的认知任务，RAG与智能体能力进行了深度融合，由此诞生了Agentic RAG这一新范式。 在此范式中，RAG的角色发生了根本转变：它不再仅仅是外部知识的被动提供者，而是在智能体的主动规划、目标指引和反思能力驱动下，成为支撑智能行为的核心处理单元。这种融合使系统整体具备了目标导向、迭代优化和自主决策的能力，显著提升了人机交互的深度与质量。具体而言，Agentic RAG能够理解复杂任务，自主拆解问题，规划检索策略，并在获取初步信息后评估结果质量，决定是否深入探索，从而胜任传统RAG难以应对的多步骤复杂任务。
|
||||
|
||||
|
||||
|
||||
Agentic RAG实现上述复杂任务处理的关键，在于其建立了一个多层次的主动循环工作机制。 面对复杂查询，智能体首先分析问题本质，将其拆解为子问题，并为每个子问题设计精准的检索策略。获得初步结果后，智能体进行评估与反思，判断信息的完整性和相关性，识别知识缺口，并动态生成更精确的新查询。这种迭代过程常包含多跳检索，即基于前一轮结果发现新的检索方向，形成类似人类研究者的知识探索链条。然而，要支撑这种持续的、迭代的智能行为，尤其是实现长期交互中的个性化和知识积累，仅依赖单次会话的短期上下文（短期记忆）是远远不够的。这引出了对长期、结构化记忆能力的需求。
|
||||
|
||||
正是为了满足这一需求，RAG被赋予了作为智能体长期记忆系统的角色，构建了一个完整的外部记忆架构。 该系统与负责维护当前会话上下文的短期记忆形成互补。该长期记忆系统的核心运作依赖于三项关键机制：
|
||||
第一，结构化索引能力：使智能体能够为海量非结构化数据建立多维索引体系（如按时间、主题或实体关系），支持多角度高效检索，模拟人脑通过不同线索回忆信息的方式。
|
||||
第二，智能遗忘机制：通过价值评估算法，系统对使用频率低、相关性弱或过时的信息进行权重衰减或选择性剔除，维持记忆系统的精炼高效，防止信息过载。
|
||||
第三，知识巩固过程：系统将零散对话和交互经验提炼为结构化知识，利用实体识别、关系抽取和语义聚类等技术，将碎片信息整合连接成知识图谱，完成从短期经验到长期知识的转化与沉淀。
|
||||
|
||||
这种由RAG构建的外部记忆系统，不仅极大地扩展了智能体的认知边界，更重要的是赋予了其持续学习和知识进化的能力。 它使得智能体能够在长期互动中积累经验，形成个性化的处理模式和领域专业知识体系，从而为执行更复杂、更持久的任务提供了坚实的基础。
|
||||
|
||||
# 总结
|
||||
|
||||
检索增强生成不仅是一种弥补大模型幻觉与知识滞后性的技术方案，更是将通用AI能力转化为企业深度业务价值的关键桥梁。从基础的Naive RAG演进至模块化、智能体协同的Advanced RAG，这一过程反映出RAG在各个环节均需持续深化——无论是更精细的数据处理、更科学的模型选型（Embedding、Rerank、LLM），还是更体系化的效果评测，都是构建可控、可信、高效的企业级知识系统的必经之路。同时，从各类竞赛与实践案例中汲取经验技巧，也能进一步加深对技术细节的理解。
|
||||
|
||||
随着图结构检索（Graph RAG）、多模态理解与Late Chunking等前沿方向的融合发展，RAG正不断突破传统检索生成的边界，逐步具备更深层的语义关联与可持续的记忆能力。希望通过这篇综述类文章的学习，能够帮助你掌握从原理到实践、从评估到演进的全链路方法论，从而在快速迭代的技术浪潮中，打造出真正落地、能够应对复杂业务挑战的高质量智能应用。
|
||||
|
||||
# Reference
|
||||
|
||||
[1] Ask in Any Modality: A Comprehensive Survey on Multimodal Retrieval-Augmented Generation.
|
||||
|
||||
https://arxiv.org/pdf/2502.08826
|
||||
|
||||
[2] Retrieving Multimodal Information for Augmented Generation: A Survey.
|
||||
|
||||
https://arxiv.org/pdf/2303.10868
|
||||
|
||||
[3] A Survey on RAG Meeting LLMs: Towards Retrieval-Augmented Large Language Models.
|
||||
|
||||
https://arxiv.org/pdf/2405.06211
|
||||
|
||||
[4] Retrieval-Augmented Generation for Large Language Models: A Survey.
|
||||
|
||||
https://arxiv.org/pdf/2312.10997
|
||||
|
||||
[5] LightRAG: Simple and Fast Retrieval-Augmented Generation.
|
||||
|
||||
https://arxiv.org/pdf/2410.05779
|
||||
|
||||
[6] Agentic Retrieval-Augmented Generation: A Survey on Agentic RAG.
|
||||
|
||||
https://arxiv.org/pdf/2501.09136
|
||||
|
||||
[7] ERAGent: Enhancing Retrieval-Augmented Language Models with Improved Accuracy, Efficiency, and Personalization.
|
||||
|
||||
https://arxiv.org/pdf/2405.06683
|
||||
|
||||
[8] Graph Retrieval-Augmented Generation: A Survey.
|
||||
|
||||
https://www.arxiv.org/pdf/2408.08921
|
||||
|
||||
[9] Evaluation of Retrieval-Augmented Generation: A Survey.
|
||||
|
||||
https://arxiv.org/pdf/2405.07437
|
||||
|
||||
[10] Retrieval Augmented Generation Evaluation in the Era of Large Language Models: A Comprehensive Survey.
|
||||
|
||||
https://arxiv.org/pdf/2504.14891
|
||||
|
||||
[11] From Local to Global: A Graph RAG Approach to Query-Focused Summarization.
|
||||
|
||||
https://arxiv.org/pdf/2404.16130
|
||||
|
||||
[12] RAG vs. GraphRAG: A Systematic Evaluation and Key Insights.
|
||||
|
||||
https://arxiv.org/pdf/2502.11371
|
||||
|
||||
[13] Introduction to RAG | LlamaIndex Python Documentation.
|
||||
|
||||
https://developers.llamaindex.ai/python/framework/understanding/rag/
|
||||
|
||||
[14] All-in-RAG | 大模型应用开发实战：RAG 技术全栈指南.
|
||||
|
||||
https://datawhalechina.github.io/all-in-rag/#/en/
|
||||
|
||||
[15] Ilya Rice: How I Won the Enterprise RAG Challenge.
|
||||
|
||||
https://abdullin.com/ilya/how-to-build-best-rag/
|
||||
|
||||
[16] RAG Research Table – Awesome Generative AI Guide (GitHub).
|
||||
|
||||
https://github.com/aishwaryanr/awesome-generative-ai-guide/blob/main/research_updates/rag_research_table.md
|
||||
|
||||
[17] RAG is dead, long live agentic retrieval.
|
||||
|
||||
https://www.llamaindex.ai/blog/rag-is-dead-long-live-agentic-retrieval
|
||||
|
||||
[18] LLM/RAG Zoomcamp 課外補充 5：RAG Evolution 常見評估方法和市場偏好.
|
||||
|
||||
https://vip.studycamp.tw/t/llmrag-zoomcamp-%E8%AA%B2%E5%A4%96%E8%A3%9C%E5%85%85-5%EF%BC%9Arag-evolution-%E5%B8%B8%E8%A6%8B%E8%A9%95%E4%BC%B0%E6%96%B9%E6%B3%95%E5%92%8C%E5%B8%82%E5%A0%B4%E5%81%8F%E5%A5%BD/8185
|
||||
|
||||
[19] How to Evaluate Retrieval Augmented Generation (RAG) Applications.
|
||||
|
||||
https://zilliz.com.cn/blog/how-to-evaluate-rag-zilliz
|
||||
|
||||
[20] RAG is not Agent Memory.
|
||||
|
||||
https://www.letta.com/blog/rag-vs-agent-memory
|
||||
|
||||
[21] Richmond Alake. LinkedIn post on #100DaysOfAgentMemory, RAG and MemoRizz.
|
||||
|
||||
https://www.linkedin.com/posts/richmondalake_100daysofagentmemory-rag-memorizz-activity-7348281860843577346-LM7Y/
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 924 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 274 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 102 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 224 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 380 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 238 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 288 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 848 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 286 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 196 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 295 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 439 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 139 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 132 KiB |
@@ -0,0 +1,211 @@
|
||||
# 扩展知识 6 - Zeabur 是什么，以及如何部署 Web 应用
|
||||
|
||||
在本教程中，我们将介绍 Zeabur——一个用于部署 Web 服务的平台。它可以帮助我们快速完成从“写好代码”到“让别人可以在互联网上访问你的网站”的完整流程。
|
||||
|
||||
# 什么是“部署”？
|
||||
|
||||
在开始之前，我们先弄清楚“部署（Deployment）”到底是什么意思。任何一个网站想要被外部用户访问，都必须有一个可以公开访问的网络地址（这个地址可以是 IP 地址，比如 123.45.67.89，也可以是域名，比如 [google.com](https://google.com/) 等）。但只有地址是不够的——你写好的网页代码（例如 HTML、CSS、JavaScript 文件，或者使用 React、Vue 等框架写的项目），以及相关的图片 / 视频资源，都必须“放”在一台 24 小时在线的服务器上，由它来响应网络请求，这样任何人的浏览器才能访问并下载这些资源。
|
||||
|
||||
|
||||
|
||||
图片来源：https://www.hostinger.com/tutorials/what-is-cloud-hosting
|
||||
|
||||
把资源上传、配置好环境并让服务“跑起来”的整个过程，就被称为 **部署（Deployment）**。
|
||||
|
||||
简单来说：你在自己电脑上写好的网页，只要在本机启动程序，就只能通过本地地址在自己的浏览器里访问，因为这些代码只存在于你的硬盘上。“部署”就是把你的代码和资源转移到一台连接着公网的专业服务器上，并做好配置，让这台服务器知道“别人访问时我要怎么响应”——比如：当有人在浏览器中输入你的域名时，服务器会立刻找到对应的网页文件，把内容传回给对方的设备，从而让用户看到你的页面。
|
||||
|
||||
如果手动部署，一个项目往往需要好几个步骤，每一步都可能踩坑。常见关键步骤包括：
|
||||
|
||||
1. **服务器准备**：你需要先购买云服务器（比如阿里云、腾讯云、或 AWS EC2），选择服务器所在地区（如上海、新加坡）、配置（CPU、内存、磁盘大小等），还要学会如何远程连接服务器（例如通过 SSH 工具登录）。
|
||||
|
||||
2. **环境配置**：Web 应用需要在特定“环境”中才能运行——例如运行 Node.js 项目必须先安装 Node.js；运行 Python 项目必须安装 Python 以及对应的第三方库。如果环境版本不匹配，程序就可能报错、无法启动。
|
||||
3. **上传资源**：你需要把本地的代码和资源上传到服务器上，常用的方法包括 FTP 或 Git。如果项目体积比较大（比如包含视频文件），中途一旦断线，有时需要重新上传。
|
||||
|
||||
|
||||
|
||||
4. **启动服务并测试**：上传完成后，你还需要在服务器上执行命令启动应用，并测试“分配的网络地址是否能访问”。如果访问不了，有可能是服务器防火墙没有放行对应端口（比如你的应用监听 3000 端口，但该端口被防火墙拦截），也可能是程序本身有 Bug，这时就需要查看服务器日志进行排查。
|
||||
> 💡 可以把端口理解为区分同一台设备上不同应用的“房间号”，而 IP 则是这台设备的“门牌号”。IP 和端口合在一起（IP:port），就可以精确定位到某一个网络服务。
|
||||
5. **维护与更新**：后续每次你修改代码，都要重新上传并重启服务。如果服务器宕机（例如断电、网络故障），还需要手动重启应用，有时还要额外配置“进程守护工具”，让程序在异常退出后自动拉起。
|
||||
|
||||
像 Zeabur 这样的“低代码部署平台”，就是为了解决上述复杂问题而诞生的。它会帮你自动完成“买服务器、配环境、上传代码、启动服务、监控运行”等步骤。你只需要把自己的代码仓库（比如 GitHub 或 GitLab）连接到 Zeabur，它就会自动拉取代码、识别应用类型、配置对应的运行时环境，最后给你一个可以被任何人访问的公网地址。它甚至可以一键绑定你自己的域名（例如把 your-app.zeabur.app 改成 your-app.com）。
|
||||
|
||||
|
||||
|
||||
接下来，我们会一步步演示如何使用 Zeabur，从“代码仓库”走到“公开可访问的网页”，全程不需要手写任何服务器命令。当然，你也可以使用 Vercel（同样有免费额度）来做类似的简单 Web 部署。不过，[Vercel](https://vercel.com/) 在部分网络环境下访问不太稳定，有兴趣的同学可以课后自行学习（操作也很简单：就是把 GitHub 项目连上即可）。
|
||||
|
||||
# 使用 Zeabur 部署 Dify
|
||||
|
||||
在之前的课程中，我们已经简单接触过 Dify。现在，我们可以通过 [Zeabur](https://zeabur.com/projects) 非常轻松地启动自己的 Dify 服务。首先打开 [控制台页面](https://zeabur.com/projects)，我们先看一下上面的各个区域。
|
||||
|
||||
|
||||
|
||||
在这个页面上，你首先能看到许多方块，这些就是已经启动的服务。在顶部菜单中，你会看到 Agent、Servers、Docs、Templates 等几个选项，它们分别代表：
|
||||
|
||||
1. **Agent**：可以打开 Zeabur 内置的智能助手（Agent），向它提问如何操作，或者查询当前服务器的状态。
|
||||
2. **Servers**：在这里可以添加你自己购买的云服务器，或者直接通过 Zeabur 购买服务器。
|
||||
3. **Docs**：查看 Zeabur 的完整文档说明。
|
||||
4. **Templates**：这里列出了所有内置的模板镜像。
|
||||
|
||||
> 这里提到的“镜像（Image）”，可以理解为“包含代码和运行环境的压缩包”。当某个服务在一台服务器上成功跑起来之后，我们可以选择把“这套运行环境 + 代码”打包成镜像。之后，在任何新服务器上，只要把这个压缩包解压并运行，就不需要重新配置环境和代码，服务就能直接跑起来。
|
||||
|
||||
在页面右上角，你还能看到自己的余额。默认情况下，每个月会有 5 美元左右的免费额度。关于细节计费规则暂时可以不用太在意，只需要知道：只要服务器在运行，就会消耗额度。
|
||||
|
||||
|
||||
|
||||
点击余额可以查看每日的消耗明细。
|
||||
|
||||
|
||||
|
||||
现在我们来创建自己的 Dify 服务。首先，在 [控制台首页](https://zeabur.com/projects) 点击 “New Project”。
|
||||
|
||||
|
||||
|
||||
接下来是各个创建方式的解释：
|
||||
|
||||
1. **GitHub**
|
||||
可以连接到你的 GitHub 账号。绑定之后，就可以直接从 GitHub 仓库里选择项目部署（GitHub 是目前全球最大的代码托管平台）。
|
||||
2. **Template（模板）**
|
||||
可以基于模板来部署服务。Zeabur 内置了很多预设项目模板（例如 Dify、n8n 等），你可以基于这些模板快速创建并部署应用。
|
||||
|
||||
3. **Databases（数据库）**
|
||||
用于部署数据库服务，比如 MySQL、MongoDB 等常见数据库。
|
||||
|
||||
4. **Functions（函数）**
|
||||
可以部署函数服务，你可以编写 JavaScript 或 Python 代码，让它们以函数的形式被调用。
|
||||
|
||||
|
||||
|
||||
5. **Local Project（本地项目）**
|
||||
上传一个本地文件夹，Zeabur 会自动识别其中的启动脚本。这适合将你已经在本地开发好的项目快速部署到 Zeabur 上。
|
||||
|
||||
6. **Docker Image**
|
||||
部署已经打包好的 Docker 镜像。如果你的项目已经被打成了 Docker 镜像（例如存放在 Docker Hub 或其他镜像仓库中），可以在这里直接部署。
|
||||
|
||||
7. **Cursor**
|
||||
如果你安装了 Cursor（例如 Cursor IDE），可以通过这个入口将 Cursor 中的项目直接部署到 Zeabur。
|
||||
|
||||
如果你想部署自己的 Dify 服务，推荐选择 **Template** 方式，然后在搜索框中输入 “dify”。可以看到很多由不同作者维护的版本，你可以任选其一（比如 v1.6.0 版本）。
|
||||
|
||||
|
||||
|
||||
接着，输入任意一个名称，Zeabur 会基于这个名称生成一个临时的自定义域名。之后所有人都可以通过这个网址访问你的服务。
|
||||
|
||||
|
||||
|
||||
创建完成后，你会看到多个程序（服务）依次启动。需要耐心等待所有服务都进入“已启动”状态。（Dify 服务是由多个程序组成的，每个程序负责不同的功能，它们之间会相互协作。）
|
||||
|
||||
一般来说，你只需要点击左侧的 Dify 应用，就可以看到默认的访问入口地址。但在本例中，由于前面还套了一层 nginx，你需要点击 nginx 服务来获取最终访问地址。可以理解为：nginx 就是负责对外统一“收发请求”的主程序，它会把外部访问的地址分发给内部各个服务。点击左侧的 Nginx，在详情页中可以看到当前的服务地址，然后在浏览器里打开这个地址，等待服务完全启动。
|
||||
|
||||
|
||||
|
||||
稍等片刻后，你就能看到 Dify 的登录界面了。输入邮箱地址和注册密码，就可以开始使用你自己的 Dify 服务了。
|
||||
|
||||
|
||||
|
||||
如果你有兴趣，还可以顺便启动一个 n8n 服务。n8n 也是海外非常流行的一款 AI 工作流平台。
|
||||
|
||||
|
||||
|
||||
# ⚠️ 如何停止和删除项目
|
||||
|
||||
由于启用服务器相关资源都会产生费用，我们在使用时一定要养成“及时关闭不用服务”的习惯，避免把每个月的免费额度消耗完。
|
||||
|
||||
如果要找到项目的管理入口，首先点击项目中的 “Settings” 选项。
|
||||
|
||||
|
||||
|
||||
进入设置页面后，将页面拉到最下方，你会看到类似下面的界面：
|
||||
|
||||
|
||||
|
||||
你可以点击 “Suspend All Services” 来暂停所有服务以降低费用；如果服务出现问题，可以点击 “Restart All Services” 对全部服务进行重启。如果你确定不再需要这个项目，可以点击 “Delete Project” 将整个项目彻底删除。
|
||||
|
||||
# 使用 Zeabur 与 Trae 部署贪吃蛇游戏
|
||||
|
||||
在本教程的下一个部分，我们会体验 Zeabur 的一些进阶用法。我们先用 Trae 生成一个贪吃蛇小游戏，再把它部署到 Zeabur 的服务器上，并配置一个可公开访问的链接，让任何人都可以打开你的游戏。
|
||||
|
||||
第一步，是在本地使用 Trae 创建一个贪吃蛇项目。
|
||||
|
||||
### 使用 HTML 框架实现
|
||||
|
||||
|
||||
|
||||
对于 Trae 来说，生成一个基于 HTML 的贪吃蛇网页游戏非常简单。游戏生成完成后，你只需要按照前面介绍的 Zeabur 本地部署方式，把包含所有文件的文件夹上传上去即可。
|
||||
|
||||
|
||||
|
||||
完成后，你就会进入该服务的详情界面：
|
||||
|
||||
|
||||
|
||||
点击左侧的 “Network” 选项，在页面中找到 “Public Address” 区域。点击 “Generate Domain”，即可生成一个对外访问地址，你可以输入任意喜欢的名称。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
生成完成后，只要在浏览器中打开这个地址，就可以运行你自己的贪吃蛇游戏了。其它 HTML 类型的 Web 应用也可以用完全相同的方式来部署。
|
||||
|
||||
|
||||
|
||||
### 使用 React 框架实现
|
||||
|
||||
前面我们学习了如何部署基于 HTML 的 Web 应用。接下来，我们再尝试部署一个目前更常用的前端框架：React 应用。相比纯 HTML，React 被认为是一种更加成熟、现代的前端开发框架。它通过组件化的方式组织页面结构，能够显著加快复杂页面的开发，是企业级项目中非常主流的选择。
|
||||
|
||||
|
||||
|
||||
#### 重构为 React 架构
|
||||
|
||||
在 Trae 中，你只需要向 Agent 说明：“帮我把这份代码重构成 React 架构”，就可以比较轻松地把原本基于 HTML 的结构重构成 React 项目。
|
||||
|
||||
|
||||
|
||||
不过，相比简单的 HTML 文件，React 应用依赖更复杂的构建工具和项目结构，因此部署过程也会稍微麻烦一些。一个典型的问题体现在端口设置上：默认情况下，React 应用一般会监听 3000 端口（你也可以在配置文件或启动日志中看到这一点）。
|
||||
|
||||
然而，在 Zeabur 上这样部署会失败——因为 Zeabur 只支持监听 8080 端口的应用。也就是说，如果想让 React 应用在 Zeabur 上正常运行，我们必须先把默认监听端口从 3000 改成 8080。
|
||||
|
||||
要正确进行这一步配置，我们需要先弄清楚两个概念：什么是“端口（Port）”，以及“监听端口（Listening Port）”是什么意思。
|
||||
|
||||
#### 什么是端口？
|
||||
|
||||
> 在计算机网络中，端口可以理解为一个“逻辑通信端点”，用来区分同一台设备上运行的不同网络服务。简单类比的话，如果 IP 地址好比一个“门牌号”（例如 162.128.1.1），那端口号就像这栋楼里不同房间的“房间号”——每个房间对应一个服务（例如 Web 服务器、邮箱服务，或者你的 React 应用）。
|
||||
>
|
||||
> 端口号用 16 位整型表示，取值范围是 0 到 65535。
|
||||
|
||||
如果不想记这些细节，可以简单理解：端口是构成“网络访问地址”的一个必要部分。
|
||||
|
||||
我们平时访问网站或 IP 地址时，通常不会手动加端口号，是因为 Web 的默认端口是 80 或 443（HTTPS）。大多数浏览器会自动使用这些标准端口。而对于一些特殊端口，比如 React 默认的 3000、Zeabur 要求的 8080，我们就必须在地址后面加上 `:3000` 或 `:8080` 才能访问到对应的内容。
|
||||
|
||||
#### 什么是“监听端口号”？
|
||||
|
||||
> “监听端口号”指的是某个程序在一台设备上主动“打开并监控”的端口。当一个应用设置了监听端口时，其实就是在告诉操作系统：“我会一直在这个端口上等待网络请求——只要有请求进来，就请转发给我。”
|
||||
|
||||
再形象一点地理解：假设你的电脑是一栋写字楼，IP 地址是这栋楼的地址。楼里开了很多公司或部门，它们分别占用不同的房间，房间号就是端口号。
|
||||
|
||||
当默认的 React 开发服务器启动时，它会“打开”某个房间的门，并安排“前台”在门口值班，这个房间号就是它的监听端口——3000。
|
||||
|
||||
同时，React 程序还会告诉这栋楼的“物业管理”（操作系统）：“我在 3000 号房间，请把所有寄给 3000 的信件（网络请求）都转给我。”
|
||||
|
||||
这样，当你访问 React 网站时，请求首先会到达这栋楼；物业看到请求要送到 3000 号房间，就会立刻把请求交给 React 的“前台”，由它来处理并返回结果——这就是访问 React 应用的过程。
|
||||
|
||||
当你在本地执行 `npm start`（本地启动 React 开发服务器的默认命令，也可以在 Vibe Coding 的 Agent 侧边栏中执行）时，React 开发服务器就会自动把监听端口设置为 3000。
|
||||
而 Zeabur 的平台设计决定了它只会“识别”监听 8080 端口的应用。如果你的 React 应用仍然使用默认的 3000 端口，Zeabur 就无法将请求正确转发给你的应用，最终导致部署失败。
|
||||
|
||||
#### 修改默认监听端口
|
||||
|
||||
要把 React 默认监听端口（3000）改成 Zeabur 所要求的 8080，有很多做法。最简单的方式，就是直接在 Trae 里对 Agent 下指令：“请帮我把这个 React 项目的默认端口改为 8080。”Trae 就会帮你修改项目中对应的配置文件。修改完成后，你只需重新打包并按前面的方式上传到 Zeabur 即可。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
在网络设置中指定一个访问 URL，方式和部署 HTML 项目时基本相同，就可以启动 React 版本的服务。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
对于其它需要修改端口号的程序，你也可以采用同样的思路：先改默认端口，再上传到 Zeabur 部署。至此，你已经掌握了将常见 Web 应用部署到服务器的基础技能。
|
||||
|
||||
你可以尝试让 Trae 帮你构建不同类型的应用，并把它们部署到 Zeabur 的默认服务器上。在后续课程中，我们还会学习如何把应用部署到你自己购买的云服务器上。
|
||||
|
||||
+630
@@ -0,0 +1,630 @@
|
||||
# 扩展知识 7 - CLI AI 编程工具与测试驱动开发原则
|
||||
|
||||
在本教程中，我们将介绍直接在命令行中运行的 AI 编程 Agent。它们和之前学过的 Trae、Cursor 中的 Agent 不同，CLI AI 编程工具只能在终端中使用。与集成在 AI IDE 里的 Agent 相比，它们通常具有更长的上下文窗口、更快的工具调用速度，并且可以兼容更多种类的大模型。在最新的 AI Vibe Coding 实战中，我们往往会优先使用 CLI AI 编程工具，而不是 IDE 内置的编码 Agent。
|
||||
|
||||
## 从 CLI 说起
|
||||
|
||||
还记得我们之前介绍过的 CLI 吗？CLI 指的是通过终端或命令提示符，用纯文本命令来操作软件应用，而不是依赖图形界面（GUI——你可以简单理解为电脑或手机上带按钮、可以点击操作的界面，不需要输入命令）。
|
||||
|
||||
> 在 Windows 上，常见的终端有“命令提示符（cmd）”和 “PowerShell”。你可以在电脑的运行/搜索框中输入 “cmd” 或 “powershell” 来启动这些命令行程序。
|
||||
|
||||
|
||||
|
||||
CLI 天生适合文本命令操作，在一小部分极客（追求极致的编程爱好者）群体中，CLI 甚至比 GUI 更受欢迎——他们希望所有操作都通过键盘完成，觉得动鼠标反而会拖慢自己的编码效率。
|
||||
|
||||
在工业界，CLI 往往也是最常见的接口形式，因为 GUI 需要操作系统额外绘制界面、管理窗口，对计算机资源的要求更高；而 CLI 只需要把收到的命令传给系统执行即可。因此，在连接大规模服务器集群时，我们通常只通过 CLI 进行交互。
|
||||
|
||||
|
||||
|
||||
对于许多没有 CLI 经验的同学来说，可能会觉得 CLI 操作很复杂、命令太多，甚至担心“一不小心就把电脑搞坏”。不用担心。还记得我们在前面教程里，经常让 Trae 帮忙完成各种基础操作吗？这里也可以完全照搬这个思路——我们可以让 CLI 编程工具帮我们执行所有 CLI 操作：让它帮你进入指定文件夹、搜索和处理文件、运行或复制开源项目等。整个过程都可以通过和 CLI AI 编程工具的对话来完成。
|
||||
|
||||
## 和 AI IDE 有什么不同
|
||||
|
||||
我们可以把 CLI AI 编程工具类比成之前学过的 z.ai 和 Trae。某种意义上，CLI AI 编程工具可以看成是一种特殊的 z.ai：它们同样只需要一个简单的对话入口，就会自动为你执行所有需要的操作（只是有时你需要手动打开浏览器查看最终效果）。而如果类比 AI IDE，那么 CLI AI 编程工具可以被看作是 IDE 中的 Agent 模块——也就是侧边那块对话区域。
|
||||
|
||||
|
||||
|
||||
不过，由于不同 AI IDE 对 Agent 的实现方式不同，能力差异也很大，AI 编程效果经常不稳定，因此 CLI AI 编程工具通常由大型科技公司直接开发，例如 Claude 背后的 Anthropic、ChatGPT 背后的 OpenAI 等。
|
||||
|
||||
相比其他 AI 编程 Agent，直接使用这些大厂产品往往是较优的实践，尤其是 Claude Code 本身就是为 Anthropic 内部研发团队服务的工具，从一开始就围绕“满足工程师真实需求”来设计。
|
||||
|
||||
为了更直观地对比，我们可以简单看看 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 |
|
||||
|
||||
表格来源：https://northflank.com/blog/claude-code-vs-cursor-comparison
|
||||
|
||||
简单说，CLI AI 编程工具通常可以：
|
||||
|
||||
- 支持更长时间的连续对话（甚至可以帮你“工作一整天”）。
|
||||
- 提供更长的上下文窗口（不再频繁需要你说“继续”）。
|
||||
- 响应速度更快（可以接入更多自定义模型 API）。
|
||||
|
||||
在编码相关操作上，它们通常比大部分 IDE 内置 Agent 更聪明、更稳定。
|
||||
|
||||
## 常见的 CLI AI 编程工具
|
||||
|
||||
目前虽然有很多开源实现，但在实践中我们只推荐两大类型的 CLI AI 编程工具，作为“首选组合”。你可以根据自己的习惯任选其一，强烈建议都试一试，再选出最适合你的那一个。
|
||||
|
||||
- Codex 使用 GPT-5，在整体能力上更强；
|
||||
- Claude Code 通过 GLM 4.6 转发 API，整体体验接近 Claude 4，但价格更便宜。
|
||||
|
||||
不过，哪一个在实际项目中更好用，只能通过亲自测试来判断。掌握多种 AI 编程工具始终是有益的：熟练以后，你可以在不同场景下灵活切换 Claude Code、Codex 或 Trae。如果尝试多次后发现某个工具效果一般，可以直接换一个工具或模型继续试验。
|
||||
|
||||
同时，由于模型版本更新非常迅速，建议你优先选择在“性价比（效果 / 成本）”上表现最好的方案。
|
||||
|
||||
### Claude Code
|
||||
|
||||
Claude Code 是由 Anthropic 基于 Claude 大模型能力开发的一款 AI 编程工具。它的主要交互场景在终端，同时也支持作为 VS Code 插件来使用。类似于 AI IDE 中的 Agent，它可以深度理解开发者的代码仓库，并通过自然语言指令完成端到端的开发任务——包括代码编辑、修复 Bug、执行和修复测试、管理 Git 工作流（例如解决合并冲突、创建 PR）、复杂代码讲解、执行终端命令等。
|
||||
|
||||
|
||||
|
||||
Claude Code 的优势主要体现在：极长的上下文窗口（可以处理完整文件甚至小型项目）、可以主动澄清模糊需求、自动规划和分配执行任务，以及对整个代码库内容的深度理解和解释能力。与普通 IDE Agent 相比，它更适合“沉浸式 vibe coding” 的开发流程。
|
||||
|
||||
在实际使用中，你可以通过对话指令，让它帮你创建新项目、执行 CLI 操作（例如整理文件夹、批量重命名文件、部署开源项目等）、配置开发环境（例如安装和调试 Python 环境）。如果觉得某段代码难以理解、某个目录结构不清晰，也可以直接让 Claude Code 生成结构化的分析文档，或者对特定内容进行分步骤讲解。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
如果你想系统地学习 Claude Code，可以参考 Andrew Ng 与 Anthropic 联合推出的课程：
|
||||
https://www.bilibili.com/video/BV176t2zSEpr
|
||||
|
||||
接下来，我们将学习如何使用 Claude Code。由于直接使用官方 Claude Code 的成本往往非常高（如下图所示），我们会转而使用兼容 Claude Code 协议、但基于其他大模型的 API 平台。
|
||||
|
||||
|
||||
|
||||
你需要学习下面几种不同方案（最好都尝试一遍），最后选择最适合你的那一种作为主要实践路径。
|
||||
|
||||
第一种方式是直接使用“兼容 Anthropic 接口”的 API。随着 Claude Code 的流行，越来越多的大模型服务商开始支持 Anthropic 风格的调用方式。常见的服务商包括 GLM、Kimi、DeepSeek 和 Siliconflow 等，它们都提供了兼容的 API 接口。关于具体配置，我们会在后文细讲。
|
||||
|
||||
需要注意的是，Claude Code 通常会消耗大量 token，如果你担心 API 调用产生过高费用，可以考虑购买 GLM 的月度套餐（大约 20 元/月）来控制成本。如果你想先感受一下实际花费，也可以先充值 10 元做小规模试验。
|
||||
|
||||
另一种方式是使用 “Claude Code Route” 项目。它是一个开源工具，不仅支持所有常见的 API 调用接口，还允许你针对不同场景精细配置要使用的模型，并且支持对接本地部署的大模型。但由于这一方案的配置相对复杂，建议你先从第一种方案入手。
|
||||
|
||||
#### 使用智谱 GLM 作为后端（推荐）
|
||||
|
||||
GLM（General Language Model）是智谱 AI 自主研发的一系列大型语言模型。GLM-4.6 是当前 GLM 系列的最新版本，其核心亮点是在代码能力上的优异表现（在公开基准和真实任务中对标 Claude Sonnet 4，在国内处于第一梯队）。
|
||||
|
||||
|
||||
|
||||
它还将上下文窗口扩展到 200K，可以更加从容地处理长文本和大体量代码，同时加强了推理与工具调用能力，在性能和成本之间取得了不错的平衡。
|
||||
|
||||
|
||||
|
||||
在接入 GLM 之前，我们需要先安装 Claude Code。
|
||||
|
||||
如果你觉得命令行安装步骤麻烦，或者中途出现错误，可以直接让 Trae 的 Agent 帮你完成安装。
|
||||
|
||||
```Python
|
||||
# 安装 Claude Code
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
|
||||
# 进入你的项目
|
||||
cd your-awesome-project
|
||||
|
||||
# 启动 Claude Code
|
||||
claude
|
||||
|
||||
# 按 Ctrl+C 退出 Claude
|
||||
```
|
||||
|
||||
接下来，我们需要修改 Claude Code 的默认 API 请求地址，使其支持 GLM 的 API 服务。你可以直接复制下面的内容，让 Trae 帮你创建对应的环境变量；也可以选择把它们永久写入系统环境变量（如果出现问题，同样可以让 Agent 帮忙修改）。
|
||||
|
||||
首先，你需要先获取 GLM 的 API Key，并用你自己觉得最方便的方式保存好。
|
||||
|
||||
国内版地址：https://bigmodel.cn/usercenter/proj-mgmt/apikeys
|
||||
国际版地址：https://z.ai/manage-apikey/apikey-list
|
||||
|
||||
如果你使用的是 **国内版 GLM**，请使用以下变量配置：
|
||||
|
||||
```Python
|
||||
# 在 Cmd 中运行以下命令
|
||||
# 注意将 `your_zhipu_api_key` 替换为你刚刚获取到的 API Key
|
||||
setx ANTHROPIC_AUTH_TOKEN your_zhipu_api_key
|
||||
setx ANTHROPIC_BASE_URL https://open.bigmodel.cn/api/anthropic
|
||||
```
|
||||
|
||||
如果你使用的是 **国际版 GLM**，请使用下面的配置：
|
||||
|
||||
```Python
|
||||
# 在 Cmd 中运行以下命令
|
||||
# 同样注意替换掉 `your_zai_api_key`
|
||||
setx ANTHROPIC_AUTH_TOKEN your_zai_api_key
|
||||
setx ANTHROPIC_BASE_URL https://api.z.ai/api/anthropic
|
||||
```
|
||||
|
||||
你可以直接在 Trae 中输入类似下面的提示词：
|
||||
|
||||
⚠️ 如果你是通过 Trae 帮你配置“永久环境变量”，那么配置完成后 **必须重启 Trae**，否则它内置终端里的环境变量不会更新，可能导致登录失败或网络连接错误。
|
||||
|
||||
```Python
|
||||
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):
|
||||
681fea485851d29060cc.13gfaendggaFOhb
|
||||
|
||||
please help me configure and start Claude Code
|
||||
```
|
||||
|
||||
你会看到类似下面的过程输出：
|
||||
|
||||
|
||||
|
||||
> 💡 什么是环境变量？
|
||||
>
|
||||
> 环境变量本质上是一组存储在操作系统中的“键值对”配置信息，通常以 “变量名 = 具体值” 的形式存在。只要提前在终端或系统设置中配置好，程序就可以随时读取这些变量来获取相关信息。由于环境变量可以直接在终端中写入，而无需修改代码本身，我们通常会把访问大模型所需的密钥存放在环境变量里，以避免泄露。程序只需要读取对应环境变量，就能完成大模型调用。
|
||||
>
|
||||
> 在 Windows 系统中，环境变量除了用于存储大模型的访问密钥，还常常用来保存命令行工具的“调用路径”。
|
||||
>
|
||||
> 我们知道终端本身也是一个程序。有时我们希望在终端里启动某个外部程序，例如在终端中输入 `claude` 来启动 Claude Code。之所以可以直接输入 `claude` 就运行，是因为终端会读取系统的环境变量，其中的 PATH 变量里包含了 Claude Code 可执行文件所在的目录，所以终端能够找到并执行它（等价于在终端中粘贴那段程序的绝对路径再按回车）。
|
||||
>
|
||||
> 一个典型的环境变量可能长这样：`PATH=C:\Windows\system32;C:\Program Files\Python`。这样我们就可以在任何路径下执行系统中的这些程序，例如直接在命令行键入 `python` 启动 Python 解释器。
|
||||
>
|
||||
> 如果你想查看系统当前的环境变量，可以在 Windows 搜索中输入“环境变量”，在弹出的“编辑系统环境变量”窗口中就能看到所有变量及其值。有的变量用于存储大模型密钥，有的则用于添加程序目录，方便在任意路径下调用。
|
||||
|
||||
现在，你就可以使用最新的 GLM 来进行 Claude Code 开发了。你可以尝试重新跑一遍之前的项目，或者重新挑战那些 Trae 没有完成好的任务，对比看看体验上的差异。
|
||||
|
||||
🎉 反复“推倒重来”并不是浪费时间——你每重做一遍，技能都会更扎实一分。
|
||||
|
||||
用和 GLM 完全相同的思路，也可以轻松接入其他支持 Anthropic 兼容格式的接口。
|
||||
|
||||
#### 使用 Kimi K2 作为后端（推荐）
|
||||
|
||||
https://platform.moonshot.cn/console/account
|
||||
|
||||
```Plain
|
||||
export ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic
|
||||
export ANTHROPIC_AUTH_TOKEN=sk-YOURKEY
|
||||
```
|
||||
|
||||
#### 使用 DeepSeek 作为后端（推荐）
|
||||
|
||||
https://platform.deepseek.com/usage
|
||||
|
||||
```Bash
|
||||
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
|
||||
export ANTHROPIC_AUTH_TOKEN=YOU_DEEPSEEK_API_KEY
|
||||
export API_TIMEOUT_MS=600000
|
||||
export ANTHROPIC_MODEL=deepseek-chat
|
||||
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat
|
||||
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
|
||||
```
|
||||
|
||||
#### 其他兼容 Anthropic 的 API
|
||||
|
||||
Siliconflow：
|
||||
|
||||
```Bash
|
||||
export ANTHROPIC_BASE_URL="https://api.siliconflow.cn/"
|
||||
export ANTHROPIC_MODEL="moonshotai/Kimi-K2-Instruct-0905" # 可以自行修改所需模型
|
||||
export ANTHROPIC_API_KEY="YOUR_SILICONCLOUD_API_KEY" # 请替换 API Key
|
||||
```
|
||||
|
||||
阿里云 DashScope（Aliyuncs）：https://help.aliyun.com/zh/model-studio/get-api-key
|
||||
|
||||
```Python
|
||||
export ANTHROPIC_BASE_URL="https://dashscope.aliyuncs.com/apps/anthropic"
|
||||
export ANTHROPIC_API_KEY="YOUR_DASHSCOPE_API_KEY"
|
||||
```
|
||||
|
||||
#### 使用 Claude Code Route 作为后端（进阶用法）
|
||||
|
||||
上面我们讲解了如何用 GLM 官方 API 替换 Claude Code 的 Anthropic 接口。接下来，我们来看一下 Claude Code Router 这个工具是如何让 Claude Code 适配更多模型 API 的。
|
||||
|
||||
[Claude Code Router](https://github.com/musistudio/claude-code-router) 是一款专门为 Claude Code 设计的智能路由增强工具。它的核心作用，是帮助用户按需将 AI 请求分发到不同平台上的模型，并可以高度自定义。它支持接入几十个平台，包括 OpenRouter、DeepSeek、Ollama、Gemini 等，也可以按场景将任务路由到特定模型，比如 GLM-4.5、Kimi-K2、Qwen3-Coder 等。举例来说，你可以将后台任务自动交给本地 Ollama，以节省成本；将长文本 / 长代码任务交给 Gemini-2.5-Pro；把代码讲解交给 DeepSeek。
|
||||
|
||||
|
||||
|
||||
该工具还提供了方便的 UI/CLI 配置管理能力，并通过“转换器（converter）”适配不同平台的 API 格式。它支持 GitHub Actions 等自动化集成以及自定义扩展，解决了“单一模型无法覆盖所有场景”以及“频繁切换平台很麻烦”的问题，帮助用户更灵活、低成本地利用 AI 工具。
|
||||
|
||||
|
||||
|
||||
下面我们简单介绍如何安装 Claude Code Router。大致需要以下步骤（同样可以让 Trae 帮你执行），以准备好相关环境：
|
||||
|
||||
```Markdown
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
npm install -g @musistudio/claude-code-router
|
||||
```
|
||||
|
||||
安装完成后，你需要确认本地可以使用 `ccr` 命令。如果看到类似下面的输出，说明安装成功：
|
||||
|
||||
|
||||
|
||||
接下来，有两种方式来初始化和配置模型：
|
||||
|
||||
- 使用 CCR 自带的 UI，在浏览器中打开它提供的配置页面进行操作；
|
||||
- 直接修改 CCR 的默认配置文件（本质上 UI 也是在修改配置文件，只是提供了更直观的界面）。
|
||||
|
||||
如果选择使用 CCR UI，你会看到类似下面的界面：
|
||||
|
||||
|
||||
|
||||
此时点击 “Add Provider” 按钮，就会看到如下界面。你需要：
|
||||
|
||||
1. 在 Name 中输入模型提供商的名字；
|
||||
2. 在 API Full URL 中填写该提供商的 OpenAI 兼容接口地址；
|
||||
3. 在 API Key 中填写对应平台的 API Key；
|
||||
4. 在 Models 区域中填写模型名称，点击 “Add Model” 添加；
|
||||
5. 最后点击 “Save” 保存配置。
|
||||
|
||||
（界面往下滚动还有很多高级选项，但目前你可以先忽略它们。）
|
||||
|
||||
|
||||
|
||||
下面是 DeepSeek 与 Kimi 的配置示例：
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
保存模型配置后，还需要在右侧 Router 区域中指定默认模型（Default）。点击对应的下拉选择，将其设置为 `kimi`（推荐），然后在右上角点击 `Save and Restart`。
|
||||
|
||||
|
||||
|
||||
之后，只需在终端中输入 `ccr code`，即可通过 Claude Code Router 启动 Claude Code 的编码工作流。
|
||||
|
||||
|
||||
|
||||
#### Claude Code 的进阶用法
|
||||
|
||||
很多人最开始使用 Claude Code 时，只把它当成普通对话工具来用。但实际上，它内置了很多丰富的能力，能够让你使用起来更高效、灵活。下面是一些常见命令和用法示例：
|
||||
|
||||
参考文档：
|
||||
|
||||
https://docs.claude.com/en/docs/claude-code/cli-reference
|
||||
https://docs.claude.com/en/docs/claude-code/slash-commands
|
||||
|
||||
| 命令 | 作用 | 示例 |
|
||||
| ----------------- | ----------------------------------------- | ---------------------------------------- |
|
||||
| claude | 启动交互模式 | `claude` |
|
||||
| claude "query" | 执行一次性任务并输出结果 | `claude "explain this project"` |
|
||||
| claude -p "query" | 执行一次性问题并在结束后自动退出 | `claude -p "explain this function xxxx"` |
|
||||
| claude -c | 继续最近的一次会话 | `claude -c` |
|
||||
| claude -r | 恢复上一段会话 | `claude -r` |
|
||||
| /resume | 在当前聊天中切换回上一段会话 | `claude -c`、`/resume` |
|
||||
| claude commit | 协助创建 Git 提交信息并提交代码 | `claude commit` |
|
||||
| /init | 用 CLAUDE.md 初始化项目说明 | `/init` |
|
||||
| /clear | 清空当前会话上下文，防止信息过载 | `/clear` |
|
||||
| /compact | 压缩会话历史，减少上下文 token 占用 | `/compact` |
|
||||
| /cost | 查看当前消费情况 | `/cost` |
|
||||
| /model | 切换使用的模型（用兼容 API 时一般可忽略） | `/model` |
|
||||
| /memory | 管理 CLAUDE.md 记忆文件 | |
|
||||
| /help | 显示可用命令列表 | `/help` |
|
||||
| exit or Ctrl+C | 退出 Claude Code | `exit` 或 `Ctrl+C` |
|
||||
| /agents | 高级功能，后文会说明 | |
|
||||
| /mcp | 高级功能，后文会说明 | |
|
||||
|
||||
**CLAUDE.md**
|
||||
|
||||
参考： https://www.anthropic.com/engineering/claude-code-best-practices
|
||||
|
||||
`CLAUDE.md` 是 Claude 在开始对话时会自动读取并加入上下文的特殊文件。因此，它非常适合用来记录：
|
||||
|
||||
- 常用 bash 命令
|
||||
- 核心文件和工具函数
|
||||
- 代码风格约定
|
||||
- 测试方式说明
|
||||
- 仓库协作规范（例如分支命名、是用 merge 还是 rebase 等）
|
||||
- 开发环境配置说明（例如是否使用 pyenv、推荐哪种编译器等）
|
||||
- 项目中需要特别注意的行为或坑点
|
||||
- 任何你希望 Claude “记住”的信息
|
||||
|
||||
`CLAUDE.md` 本身没有强制格式要求，只要简洁、便于人类阅读即可。例如：
|
||||
|
||||
```Plain
|
||||
# Bash commands
|
||||
- npm run build: Build the project
|
||||
- npm run typecheck: Run the typechecker
|
||||
|
||||
# Code style
|
||||
- Use ES modules (import/export) syntax, not CommonJS (require)
|
||||
- Destructure imports when possible (eg. import { foo } from 'bar')
|
||||
|
||||
# Workflow
|
||||
- Be sure to typecheck when you’re done making a series of code changes
|
||||
- Prefer running single tests, and not the whole test suite, for performance
|
||||
```
|
||||
|
||||
#### Claude Code 的内部原理
|
||||
|
||||
参考： https://github.com/shareAI-lab/analysis_claude_code
|
||||
|
||||
如果你好奇为什么 Claude Code 在很多场景下比 Trae 或 Cursor 等 Agent 编程工具更好用，我们可以简单看一下它的内部工作机制。
|
||||
|
||||
其他 CLI AI 编程工具的整体实现方式也大体类似。
|
||||
|
||||
|
||||
|
||||
Claude Code 会把编程任务拆解成一个持续的“感知—思考—行动—验证”循环，并在其中调用不同工具完成任务。它模仿人类开发者的工作流：不断“写代码 → 运行 → 看结果 → 再改进”。系统内部通过一个主任务循环不断执行步骤，在每一轮循环中，Claude 都可以调用不同工具——例如读写文件、执行命令、搜索代码等——再根据工具返回的真实结果决定下一步行动。
|
||||
|
||||
其中有几个关键特性值得注意：
|
||||
|
||||
- **流式处理（Stream Processing）**：Claude 可以一边思考一边输出结果，而不是必须等所有代码写完再执行。
|
||||
- **智能压缩（Intelligent Compression）**：长对话容易导致上下文过长，Claude 通过将历史压缩成关键信息来减少“遗忘”的概率，并通过区分长短期记忆保证高效运行。
|
||||
- **并发控制（Concurrency Control）**：内部并行设计可以让多个任务同时进行，互不干扰。
|
||||
- **子 Agent 管理（Sub-agent Management）**：实际工作中并不只相当于一个“角色”处理所有事情，你可以管理多个子 Agent 协作处理代码，每个 Agent 负责不同任务，比如专门负责测试、专门负责写文档等。
|
||||
|
||||
### Codex
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
和 Claude Code 类似，Codex 是由 OpenAI 开发的一款 AI 协作编程工具，你可以把它理解成 “OpenAI 版的 Claude Code”。它最大的优势是对 GPT-5 的高效适配。
|
||||
|
||||
从实际体验来看，GPT-5 目前响应速度更快、犯错率更低（在多轮复杂任务中正确完成的概率更高）。它的一个缺点是解释往往偏“学术”和“技术”，有时显得过于严谨、信息量很大，对初学者来说可能略微难懂。
|
||||
|
||||
你可以通过下面的命令安装 Codex：
|
||||
|
||||
```Plain
|
||||
npm i -g @openai/codex
|
||||
```
|
||||
|
||||
#### 使用 OpenAI 官方 API 作为后端
|
||||
|
||||
如果直接使用 OpenAI 官方的 Codex 入口，配置会非常简单：当你已经开通 OpenAI 订阅或申请到了相应 API 配额之后，只需要在命令行中输入 `codex` 启动程序，并按提示完成登录即可。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 使用转发 OpenAI API 的方式作为后端
|
||||
|
||||
由于官方 OPENAI API 可能存在价格较高、网络要求严格等问题，为了避免这些限制，我们也可以通过其他 API 网关服务来转发调用。
|
||||
|
||||
在这种方式下，我们只需要在第三方转发平台上购买对应的 Codex API 配额，就能获得接近原生 OpenAI Codex 的使用体验。
|
||||
|
||||
参考： https://open-dev.feishu.cn/wiki/PAqUwWG4IiuwTvkQ2sGcaQuPnXc
|
||||
充值地址： https://api.zyai.online/account/topup/recharge
|
||||
|
||||
需要注意的是，在拿到 token 配额后，我们还需要在本地配置好 API Key。
|
||||
|
||||
在密钥分组设置中，要注意选择专门用于 Codex 的那一项。
|
||||
|
||||
|
||||
|
||||
接下来，我们需要把获取到的 Key 填入下面的提示词中，并把整段提示词交给 Trae，让它帮你完成整个配置过程：
|
||||
|
||||
```Bash
|
||||
My API key is: [Paste your obtained sk-xxxxx key here]
|
||||
|
||||
Please help me complete the following configuration tasks:
|
||||
|
||||
1. Create configuration directory
|
||||
- Create a `.codex` folder under my user directory
|
||||
- Windows path should be: `C:\Users\[My Username]\.codex`
|
||||
2. Backup existing configuration (if exists)
|
||||
- Check if `.codex\config.toml` exists
|
||||
- If it exists, rename it to `config.toml.bak.[current timestamp]` (timestamp format: yyyyMMddHHmmss)
|
||||
3. Create configuration file
|
||||
- Create `config.toml` in the `.codex` directory
|
||||
- Write the following complete content:
|
||||
```toml
|
||||
preferred_auth_method = "apikey"
|
||||
|
||||
[model_providers.myrelay]
|
||||
name = "My Relay Station"
|
||||
base_url = "https://api.zyai.online/v1"
|
||||
env_key = "MYRELAY_API_KEY"
|
||||
wire_api = "responses"
|
||||
request_max_retries = 4
|
||||
stream_max_retries = 10
|
||||
stream_idle_timeout_ms = 300000
|
||||
|
||||
[profiles.myrelay]
|
||||
model_provider = "myrelay"
|
||||
model = "gpt-5"
|
||||
model_reasoning_effort = "medium"
|
||||
|
||||
[tools]
|
||||
web_search = true
|
||||
|
||||
4. Set system environment variable
|
||||
Variable name: MYRELAY_API_KEY
|
||||
Variable value: The key I gave you
|
||||
|
||||
5. Confirm completion and report back:
|
||||
|
||||
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 类似：只需要在对话框中随时输入你的想法和需求即可。
|
||||
|
||||
## CLI AI 编程工具的更多用法
|
||||
|
||||
### 用 AI 写需求文档：学会“具体化需求”
|
||||
|
||||
对于大语言模型来说，抽象需求需要被“具体化”。比如：“我很饿”是一个抽象需求，我们需要把它变成：“我肚子有点饿，可能需要吃一个红豆面包，再配一杯豆浆。”——这才是一种可以被执行的、具体的需求。
|
||||
|
||||
但把抽象需求变具体，其实是一个很花精力的过程。如果我们没有见过足够多的案例，很难快速联想到该如何把抽象问题拆解成细致的模块。这种时候，最好的办法就是让 AI 帮你完成“具体化”这一步。
|
||||
比如，我想开发一个“每日计划”应用，最朴素的想法可能是：
|
||||
|
||||
`Please help me write a daily planning app where I can write my plans each day and get reminders.`
|
||||
|
||||
AI 确实可以在这个需求基础上直接拆分任务，然后一步步完成，但中间容易出错或理解偏差。为了降低风险，我们可以让 AI 帮我们先扩写需求：
|
||||
|
||||
`Based on my needs, please elaborate and provide a more detailed Product Requirement Document for reference. My idea is: Please help me write a daily planner app that supports daily plan-writing and provides reminders .`
|
||||
|
||||
这时，AI 可能会给出类似下面这样完整的 PRD：
|
||||
|
||||
```Plain
|
||||
Product Requirements Document (PRD): “Today’s Plan” App
|
||||
Document Version: 1.0
|
||||
Creation Date: October 27, 2023
|
||||
Author: (Your Name/Product Manager)
|
||||
|
||||
1. Product Introduction
|
||||
1.1 Product Name
|
||||
Today's Plan
|
||||
1.2 Product Vision
|
||||
“Today’s Plan” is a minimalist and highly efficient daily planning and reminder tool, dedicated to helping users eliminate procrastination and forgetfulness, plan every day clearly, and ensure tasks are carried out through an intelligent reminder system—ultimately enabling users to gain a stronger sense of control and achievement over their time.
|
||||
1.3 Target Users (User Personas)
|
||||
We mainly serve three types of users:
|
||||
Students (Xiao Ming):
|
||||
Characteristics: Multiple tasks such as courses, assignments, club activities, exam prep, needing organized time arrangement.
|
||||
Pain Points: Easily forget small tasks or assignment deadlines; feel overwhelmed switching between tasks; want to build regular study and life habits.
|
||||
Needs: A simple tool to list daily to-dos and provide reminders before class/self-study.
|
||||
Office Workers (Zhang Wei):
|
||||
Characteristics: Fast-paced work, many meetings, reports, project milestones, and personal affairs (fitness, picking up children).
|
||||
Pain Points: Easily forget important meetings or work milestones; get interrupted by urgent tasks and forget the original plan; feel busy but inefficient at end of day.
|
||||
Needs: Need a tool to quickly record and schedule daily work and send strong reminders at key times (e.g., 15 minutes before meetings).
|
||||
Freelancers/Self-disciplined Seekers (Li Na):
|
||||
Characteristics: High freedom of time, but strong self-management required for work output and personal growth.
|
||||
Pain Points: Easily procrastinate, lack external supervision; start the day without a clear plan, leading to low time utilization.
|
||||
Needs: Need a tool to help build a daily fixed routine (Morning Routine) and review daily achievements for positive feedback.
|
||||
|
||||
2. User Stories
|
||||
As a user, I want to quickly create today’s plan list so I have an overview of all my tasks for the day.
|
||||
As a user, I want to set specific start and end times for each task so I can create a visual timeline.
|
||||
As a user, I want to receive push notification reminders before a task starts so I won’t miss any important arrangements.
|
||||
As a user, I want to customize the reminder time (such as 5, 15, or 60 minutes in advance) so reminders better fit my habits.
|
||||
As a user, I want to easily mark completed tasks so I can feel accomplished and clearly see my progress.
|
||||
As a user, I want to see a summary of my completed plans at the end of each day for reviewing and self-motivation.
|
||||
As a user, I want to conveniently edit and delete tasks to handle last-minute changes.
|
||||
As a user, I want to view plans and achievements from previous days to review my efficiency and habits.
|
||||
|
||||
3. Feature Breakdown
|
||||
Core Features (MVP - Minimum Viable Product)
|
||||
Module 1: Plan Management
|
||||
3.1.1 Daily Plan Homepage
|
||||
Interface: “Today” as the core view, current date shown at the top.
|
||||
View: Timeline list, clearly showing tasks scheduled from morning to evening. Tasks without a time can be listed in the top or bottom “To-do List” section.
|
||||
Interactions:
|
||||
Click the “+” button in the bottom right to quickly create a new task.
|
||||
Pull down to refresh the page.
|
||||
Swipe left/right to view yesterday’s and tomorrow’s plans.
|
||||
3.1.2 Create/Edit Task
|
||||
Entry: Click “+” on the homepage or a time slot in the list.
|
||||
Fields:
|
||||
Task title (required): Briefly describe the task, e.g., “10 AM Weekly Product Meeting.”
|
||||
Task time (optional):
|
||||
Set “start time” and “end time.”
|
||||
Provide “all-day” option for unspecified time tasks.
|
||||
Default time picker should be quick and convenient.
|
||||
Reminder setting (required, with default value): See Module 2.
|
||||
Notes (optional): Add further descriptions, links, or location info.
|
||||
Actions: Save, cancel, delete task.
|
||||
3.1.3 Task Interaction
|
||||
Mark as complete: Checkbox before each task; checking adds a strikethrough and gray background, indicating completion. Can unmark if needed.
|
||||
Edit task: Click the task itself to enter edit page.
|
||||
Delete task: Swipe left on a task to reveal “Delete” button.
|
||||
Module 2: Smart Reminder System
|
||||
3.2.1 Reminder Trigger
|
||||
Mechanism: Based on task’s set “start time” and the user’s “reminder lead time,” send a push notification from device.
|
||||
Offline Support: Locally scheduled reminders must trigger even if user is offline.
|
||||
3.2.2 Reminder Content & Format
|
||||
Notification title: App name “Today’s Plan.”
|
||||
Body: “Reminder: [Task Title] will start at [Start Time].” E.g., “Reminder: Product Meeting will start at 10:00.”
|
||||
Sound: Use system default or offer several simple, effective tones.
|
||||
3.2.3 Reminder Settings
|
||||
Global Settings (in Settings page):
|
||||
User can set a default reminder time, e.g., “15 minutes before task starts.” New tasks adopt this by default.
|
||||
Single Task Settings (in create/edit page):
|
||||
Users can override global settings for important tasks, choosing specific reminder times like "on time," "5 minutes early," "30 minutes early," or "1 hour early."
|
||||
Provide “no reminder” option.
|
||||
Subsequent Features (V1.1, V2.0)
|
||||
3.3 Daily Review & Statistics
|
||||
Push a summary notification at a set time every night (e.g., 22:00): “How was your day? Take a look at your achievements!”
|
||||
Generate a simple daily report card: shows total planned tasks, completed tasks, completion rate, plus an encouraging message.
|
||||
3.4 History Review
|
||||
Calendar view to click on any past day and check its plans and completion status. Days with high completion rates marked with a special color.
|
||||
3.5 Templates
|
||||
Allow users to save a successful daily plan as a template, e.g., “Efficient Workday,” “Relaxing Weekend.”
|
||||
When creating tomorrow’s plan, one-click import a template, modify slightly to save time.
|
||||
3.6 Themes & Personalization
|
||||
Offer dark mode.
|
||||
Allow changing several primary color themes.
|
||||
|
||||
4. Non-Functional Requirements
|
||||
4.1 Performance
|
||||
Response: App launch time under 2 seconds; adding/editing tasks must be smooth and lag-free.
|
||||
Resource Use: Low battery and memory consumption in background; do not over-consume resources waiting for reminders.
|
||||
4.2 Usability
|
||||
Minimal & intuitive: UI must be minimal, primary functions accessible within 3 clicks. No tutorial needed for new users.
|
||||
Error tolerance: Offer undo (e.g. brief undo after mistakenly deleting a task).
|
||||
4.3 Reliability
|
||||
Reliable reminders: Reminder function is the product’s lifeline; must guarantee 99.99% timely and accurate delivery.
|
||||
Data loss-free: User plans must be reliably stored locally. Future versions can support cloud sync to prevent data loss on device change.
|
||||
4.4 Compatibility
|
||||
Platform: Support major iOS and Android versions (latest 3-4 releases).
|
||||
Screen: Layout must fit various phone screen sizes.
|
||||
|
||||
5. Roadmap
|
||||
V1.0 (MVP):
|
||||
Goal: Validate core value—planning & reminders.
|
||||
Features: Complete all “Core Features” described above (Plan management, smart reminders).
|
||||
V1.1 (Quick Optimization):
|
||||
Goal: Improve retention and achievement.
|
||||
Features: Add “Daily Review & Statistics,” “History Review.”
|
||||
V2.0 (Enhanced Experience):
|
||||
Goal: Increase efficiency and personalization.
|
||||
Features: Add “Templates,” “Themes & Personalization,” and start developing “Cloud Sync.”
|
||||
```
|
||||
|
||||
对比我们最开始那句“帮我写一个每天可以记计划并提醒的应用”，现在这份文档已经详细得多了。你可以根据自己的真实需求，对其中的内容进行增删修改；对于某些你不确定的模块，也可以继续让 AI 提供更多备选方案，你再挑选、合并成最终版本。
|
||||
|
||||
通过这种方式，我们可以很轻松地把抽象想法变成具体描述。对 AI 开发来说，“具体”就是生产力：需求越具体，越容易得到结构稳定、质量较高的项目。你可以尝试用这种方式重做一下之前的某个小项目，对比一下效果差异。
|
||||
|
||||
如果你觉得这类“需求提示词”太长，非常自然的做法，是把它单独写进一个 markdown 文档中，作为你的“需求文档 / 开发文档 / PRD”。之后每次让 AI 写项目时，只需要让它“参考这份文档”，而不是每次都重打一遍长提示。你也可以在迭代中不断完善这份文档，让后续项目直接受益。
|
||||
|
||||
下面是一些其他常见的使用场景：
|
||||
|
||||
### 管理文件夹
|
||||
|
||||
我们可以尝试用 CLI AI 编程工具来管理当前文件夹中的各种文件。比如，你有一堆杂乱无章的文件，需要整理归类，就可以对 Claude Code 或 Codex 说：
|
||||
|
||||
`Please help me organize the contents of the current folder. I want to group files with the same content together & I want to group files from the same time period together. Please help me handle this.`
|
||||
|
||||
### 开发新项目
|
||||
|
||||
这和我们之前在 z.ai、Trae 中的用法几乎完全一样——我们也可以直接用 CLI AI 编程工具来从零开发新项目。当然，最好提前准备好一份需求文档。
|
||||
|
||||
需求文档越细致，最终效果越好。你可以根据不断变化的想法，对文档做多轮优化；文档越完善，代码实现就越稳定、越成熟。
|
||||
|
||||
### 部署开源项目（例如 Dify）
|
||||
|
||||
对于刚接触计算机的同学来说，从 GitHub 上部署一个开源项目往往很有难度。但我们完全可以把这件事交给 Claude Code，就像我们在 Dify 教程中做的那样：
|
||||
|
||||
https://github.com/langgenius/dify
|
||||
|
||||
如果我想在本地跑起自己的 Dify，只需要把这个链接扔给 Claude Code，然后输入：
|
||||
|
||||
`I want to deploy this GitHub project ``https://github.com/langgenius/dify`` . Please help me clone the project and run it.`
|
||||
|
||||
收到你的请求后，Claude Code 会自动完成一系列操作，包括从 GitHub 拉取代码、配置运行环境、启动项目等。如果中间某一步出错或项目启动状态不正常，你再根据提示进行少量人工处理即可。除了 Dify，你也可以用 Claude Code 帮你部署大部分常见的 GitHub 开源项目——你只需要一个对话框，再加上喝一杯咖啡的时间 ☕️。
|
||||
|
||||
|
||||
|
||||
### 讲解代码与撰写文档
|
||||
|
||||
对于一些复杂项目，或者 AI 自动生成的大型项目，你可能会觉得代码太长、逻辑太多，很难看懂。这时就可以让 CLI AI 编程工具帮你“读代码”。你可以这样提问：
|
||||
|
||||
- 请帮我解释这个项目：如何运行、如何使用、后续如何修改和继续开发？
|
||||
- 请帮我说明这个项目的整体流程：程序是怎样运行的？用户在界面中可以做哪些操作？
|
||||
- 请帮我为这个项目写一份完整的文档，包括开发文档和运行文档等。
|
||||
- 请基于我当前文件夹里的所有内容，写一份详细说明，并保存到指定的 markdown 文档中。
|
||||
|
||||
### 更多玩法
|
||||
|
||||
当然，CLI AI 编程工具能做的远不止上面这些。不要只把它当作“写代码工具”，而是把它看作一个具有独立行动能力的智能 Agent。你可以让它帮你：
|
||||
|
||||
- 管理和整理本地文件；
|
||||
- 写日记、写总结；
|
||||
- 分析和修复系统错误；
|
||||
- 执行各种重复性命令行任务等。
|
||||
|
||||
也许在不久的将来，它会变成你电脑上最重要、也最懂你的 AI 伙伴。
|
||||
+136
@@ -0,0 +1,136 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<title>Vibe Coding 101</title>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0" />
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" />
|
||||
<style>
|
||||
.github-corner:hover .octo-arm {
|
||||
animation: octocat-wave 560ms ease-in-out;
|
||||
}
|
||||
@keyframes octocat-wave {
|
||||
0%,
|
||||
100% {
|
||||
transform: rotate(0);
|
||||
}
|
||||
20%,
|
||||
60% {
|
||||
transform: rotate(-25deg);
|
||||
}
|
||||
40%,
|
||||
80% {
|
||||
transform: rotate(10deg);
|
||||
}
|
||||
}
|
||||
@media (max-width: 500px) {
|
||||
.github-corner:hover .octo-arm {
|
||||
animation: none;
|
||||
}
|
||||
.github-corner .octo-arm {
|
||||
animation: octocat-wave 560ms ease-in-out;
|
||||
}
|
||||
}
|
||||
|
||||
:root {
|
||||
--sidebar-width: 230px;
|
||||
--sidebar-padding: 12px 24px;
|
||||
}
|
||||
|
||||
.markdown-section {
|
||||
padding: 24px 40px 40px 24px;
|
||||
}
|
||||
|
||||
.sidebar-nav ul {
|
||||
list-style-type: none;
|
||||
}
|
||||
|
||||
.app-sub-sidebar li {
|
||||
list-style-type: none !important;
|
||||
}
|
||||
|
||||
.app-sub-sidebar li::before {
|
||||
content: none !important;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="app"></div>
|
||||
<a href="https://github.com/datawhalechina/vibe-coding" class="github-corner" aria-label="View source on GitHub">
|
||||
<svg
|
||||
width="80"
|
||||
height="80"
|
||||
viewBox="0 0 250 250"
|
||||
style="fill: #64ceaa; color: #fff; position: absolute; top: 0; border: 0; right: 0;"
|
||||
aria-hidden="true"
|
||||
>
|
||||
<path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path>
|
||||
<path
|
||||
d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2"
|
||||
fill="currentColor"
|
||||
style="transform-origin: 130px 106px;"
|
||||
class="octo-arm"
|
||||
></path>
|
||||
<path
|
||||
d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.9,120.9 152.7,125.1 L141.0,136.9 C139.8,138.0 141.6,141.9 141.8,141.8 Z"
|
||||
fill="currentColor"
|
||||
class="octo-body"
|
||||
></path>
|
||||
</svg>
|
||||
</a>
|
||||
<script>
|
||||
window.$docsify = {
|
||||
name: 'Vibe Coding 101',
|
||||
repo: '',
|
||||
loadSidebar: true,
|
||||
subMaxLevel: 2,
|
||||
homepage: 'README.md',
|
||||
pagination: {
|
||||
previousText: '上一页',
|
||||
nextText: '下一页',
|
||||
crossChapter: true,
|
||||
crossChapterText: true
|
||||
},
|
||||
count: {
|
||||
countable: true,
|
||||
position: 'top',
|
||||
margin: '10px 0 20px 0',
|
||||
float: 'left',
|
||||
fontsize: '0.9em',
|
||||
color: 'rgb(90,90,90)',
|
||||
language: 'chinese',
|
||||
isExpected: true
|
||||
},
|
||||
plugins: [
|
||||
function (hook, vm) {
|
||||
hook.doneEach(function () {
|
||||
setTimeout(function () {
|
||||
var section = document.querySelector('.markdown-section');
|
||||
if (!section) return;
|
||||
var title = section.querySelector('h1');
|
||||
var counter = section.querySelector('.countable');
|
||||
if (title && counter && title.nextSibling !== counter) {
|
||||
title.parentNode.insertBefore(counter, title.nextSibling);
|
||||
counter.style.display = 'block';
|
||||
counter.style.float = 'none';
|
||||
counter.style.margin = '10px 0 20px 0';
|
||||
}
|
||||
}, 0);
|
||||
});
|
||||
}
|
||||
]
|
||||
};
|
||||
</script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@latest/components/prism-bash.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@latest/components/prism-python.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify-pagination@latest/dist/docsify-pagination.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.js"></script>
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css" />
|
||||
<script src="//cdn.jsdelivr.net/npm/marked@3"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify-katex@latest/dist/docsify-katex.js"></script>
|
||||
<script src="//unpkg.com/docsify-count/dist/countable.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,27 @@
|
||||
# 从创意到 AI 产品
|
||||
|
||||
我们目前正经历着由大语言模型（LLMs）驱动的 AI 技术应用的爆炸式浪潮。与过去 AI 开发严重依赖算法研究不同，现在行业的重点已转移到有效利用现有的强大 AI 模型来创建有价值的应用程序。这一转变显着降低了 AI 开发的门槛，将重心从“从头构建模型”转移到了“将 AI 能力封装成现实世界的解决方案”。
|
||||
|
||||
对于大多数初学者和开发者来说，今天最大的机会不在于发明新算法，而在于学习如何有效地调用、编排和工程化 AI 功能，以满足特定的市场和用户需求。
|
||||
|
||||
尽管有了这种转变，许多学习者发现，掌握与 AI 交互或生成内容的技能只是一个起点。一个普遍存在的挑战仍然存在：如何实现从“AI 用户”到“AI 应用创造者”的跨越。关键问题包括：如何将分散的 AI 功能集成到自动化工作流中？如何为 AI 应用程序构建健壮可靠的前端和后端，并将它们在线部署？如何跨越从开发到实际运营的关键“最后一公里”？
|
||||
|
||||
本课程正是为了解决这些关键障碍而设计的。它不拘泥于抽象理论，而是致力于 AI 原生应用开发的端到端实践培训。
|
||||
|
||||
# 为什么要学这个？它将如何帮助我的未来？
|
||||
|
||||
本课程侧重于 AI 原生应用的实际开发和创新思维的培养，专为初级水平的学生量身定制。通过理论指导和动手实践相结合，学生将逐步掌握 AI 应用开发必不可少的核心方法和创新途径：
|
||||
|
||||
* **基本掌握多模态 AI 模型的应用方法和适用场景：**
|
||||
* 能够使用 vibe coding 工具调用主流多模态理解和生成模型 API（涵盖文本、图像、视频、音频等）。
|
||||
* 能够分析不同模型的能力边界，并根据特定应用场景适当地选择模型。
|
||||
* **能够利用和分析前沿 AI 产品：**
|
||||
* 能够研究和分析行业内各种最先进的 AI 产品（基于文本、图像、视频），学习分析产品构建背后的技术原理，并了解竞争对手使用的常见实现方法。
|
||||
* **基本理解和实践不同的 AI 应用框架和核心工作流：**
|
||||
* **知识库与 AI 工作流：** 了解知识库构建的基础知识，并开发使用它们的基础和中级技能，以及设计、实施和优化 AI 工作流的能力。
|
||||
* **智能体 (Agent)：** 了解智能体的原理，并获得智能体开发和应用的初步实践经验。
|
||||
* **图像生成和编辑：** 掌握图像生成和编辑工作流中的入门级和高级技术。
|
||||
* **AI 原生应用开发和运营的实践经验：**
|
||||
* 学习使用先进的 AI 编码工具；了解前端和后端数据库的作用；并能够独立开发和部署 AI 应用程序（APP / Web 应用程序）。
|
||||
* 了解用户管理和支付等核心功能模块的实现方法。
|
||||
* 获得用户研究、产品推广和应用分享的基本技能；同时，通过与企业合作或独立运营，开始探索 AI 应用的价值创造闭环。
|
||||
@@ -0,0 +1,651 @@
|
||||
# Project 1: 如何构建贪吃蛇游戏
|
||||
|
||||
这是一个**基于项目的学习**教程。我们鼓励你跟随步骤一步步操作，并尝试复现结果。不要担心犯错或修改内容——**最重要的是：** 🎉 **完成比完美更重要**
|
||||
|
||||
在软件工程中，**迭代是正常且有价值的**。你不需要一次性创造出一个完整的产品——**从小处着手，边做边改。**
|
||||
|
||||
在本教程中，我们将学习如何使用 **vibe coding** 技巧来创建一个现代版的贪吃蛇游戏。我们将从贪吃蛇游戏的基本机制开始，然后对其进行修改，让蛇吃掉字符而不是点。最后，游戏将根据这些字符生成一首诗，并绘制一幅受这首诗启发的图画。
|
||||
|
||||
> 💡 什么是 Vibe Coding？计算机科学家 [Andrej Karpathy](https://karpathy.ai/)（OpenAI 的联合创始人之一，特斯拉前 AI 负责人）于 2025 年 2 月提出了 **vibe coding** 一词。这个概念指的是一种依赖于 LLM 的编码方法，允许程序员通过提供自然语言描述而不是手动编写代码来生成可工作的代码。
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 点击这里查看更多关于 vibe coding 的细节：
|
||||
>
|
||||
> [https://www.ibm.com/think/topics/vibe-coding](https://www.ibm.com/think/topics/vibe-coding)
|
||||
|
||||
# 你将学到
|
||||
|
||||
* 使用提示词（prompts）构建一个简单的游戏。
|
||||
* 如果你看到错误，告诉 AI 并让它帮你修复。
|
||||
* 为你的游戏添加文本和图像生成功能，使其更有趣。
|
||||
|
||||
# 1. 准备工作
|
||||
|
||||
## 1.1 我们应该使用哪些工具？
|
||||
|
||||
我们将使用一个非常简单的工具来构建一个最小化的游戏。你不需要知道如何调用大语言模型或图像生成模型。
|
||||
|
||||
这个工具叫做 [z.ai](https://chat.z.ai/)，由智谱 AI（中国领先的 LLM 公司之一）开发。它支持多种功能，如 AI 驱动的幻灯片生成、海报设计和全栈开发。在本教程中，我们将重点关注其全栈开发模块。
|
||||
|
||||
|
||||
|
||||
[z.ai](https://chat.z.ai/) 中的全栈开发模块支持网页的实时编辑和预览。
|
||||
|
||||
|
||||
|
||||
通过点击全栈开发示例，你可以看到网页创建的整个过程。
|
||||
|
||||
|
||||
|
||||
等你的咖啡泡好了，你的结果也就出来了！
|
||||
|
||||
|
||||
|
||||
你可以上下滚动浏览此网页，或点击顶部的 🧭 按钮以全屏模式查看页面。
|
||||
|
||||
|
||||
|
||||
如果你想查看此网页的源代码，可以点击右上角的图标。
|
||||
|
||||
|
||||
|
||||
你将能够看到所有代码。
|
||||
|
||||
|
||||
|
||||
## 1.2 我们需要前端开发知识吗？
|
||||
|
||||
我们在开始时不需要掌握前端甚至后端开发技能。我们只需要学习如何与大语言模型聊天，如何根据当前的运行结果向 LLM 提出新需求，以及当代码运行失败时如何向 LLM 提供准确的错误信息。
|
||||
|
||||
但我们建议你学习一些前端和后端开发的基础知识，因为这将帮助你让 LLM 创建更好的程序。
|
||||
|
||||
别担心，你只需要在学习过程中逐渐掌握这些知识，不需要一开始就是专家。
|
||||
|
||||
> 💡 更多关于前端开发的信息
|
||||
>
|
||||
> 前端开发通常意味着使用 **HTML**、**CSS** 和 **JavaScript** 来创建网站或应用程序的用户界面。然而，在本教程中，我们将跳过前端编码的复杂性，因为我们使用的工具会自动为我们生成并运行界面。
|
||||
>
|
||||
> 但了解幕后发生的事情是有帮助的。传统上，构建 Web 界面涉及编写用于结构的 **HTML**、用于样式的 **CSS** 和用于交互性的 **JavaScript**。
|
||||
>
|
||||
> 例如，这是一个非常简单的网页，但它结合了三种不同类型的代码：
|
||||
>
|
||||
> 
|
||||
>
|
||||
> * 一个简单的 HTML 按钮：
|
||||
>
|
||||
> ```HTML
|
||||
> <button>Click Me</button>
|
||||
> ```
|
||||
>
|
||||
> * 基本的 CSS 让按钮变蓝：
|
||||
>
|
||||
> ```CSS
|
||||
> button {
|
||||
> background-color: #3498db;
|
||||
> color: white;
|
||||
> border: none;
|
||||
> padding: 10px 20px;
|
||||
> border-radius: 4px;
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
> * 一点 JavaScript 来在点击按钮时显示提示：
|
||||
>
|
||||
> ```JavaScript
|
||||
> document.querySelector('button').onclick = function() {
|
||||
> alert('Button was clicked!');
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
> 当你尝试点击这个按钮时，你会在浏览器中看到一个提示信息：
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 此外，我们可以尝试理解这三种代码的深层含义：
|
||||
>
|
||||
> **什么是 HTML？**
|
||||
>
|
||||
> HTML，全称 **超文本标记语言 (HyperText Markup Language)**，是网页的骨架。它的工作是定义页面的结构和内容，如标题、段落、图像、链接，以及示例中看到的按钮本身。
|
||||
>
|
||||
> * **HTML 决定页面上有什么**：它告诉浏览器，“这是一个按钮”，“这是一段文本”，或者“在这里显示一张图片”。
|
||||
> * **它使用“标签”来组织内容**：`<button>Click Me</button>` 是一个 HTML 标签，定义了一个按钮，并在其中包含了“Click Me”这个文本。
|
||||
>
|
||||
> **什么是 CSS？**
|
||||
>
|
||||
> CSS，或层叠样式表 (Cascading Style Sheets)，负责网页的“外观和感觉”。它用于设计和美化 HTML 元素，控制颜色、字体、布局和间距等。
|
||||
>
|
||||
> * **CSS 决定页面看起来怎么样**：在我们的示例中，CSS 代码将标准 HTML 按钮变成了一个带有蓝色背景、白色文本、圆角和一些内边距的按钮。
|
||||
> * **它将内容与表现分离**：这是一个关键概念。你可以有一个用于内容的 HTML 文件，并使用一个单独的 CSS 文件来设置它的样式。这使得维护和更新整个网站的设计变得更加容易。
|
||||
>
|
||||
> **什么是 JavaScript？**
|
||||
>
|
||||
> JavaScript 是一种编程语言，它为网页添加交互性和动态行为。如果说 HTML 是骨架，CSS 是皮肤，那么 JavaScript 就是大脑和肌肉，让页面“活起来”。
|
||||
>
|
||||
> * **JavaScript 决定页面的行为**：在示例中，JavaScript 代码使得点击按钮时弹出提示框。它定义了响应用户输入时应该发生的操作。
|
||||
> * **它可以创建复杂的功能**：除了简单的提示，JavaScript 还用于处理表单提交、创建动画、在不重新加载页面的情况下加载新数据、构建像游戏这样的复杂应用程序等等。
|
||||
>
|
||||
> 随着项目变得越来越大，交互性越来越强，仅使用纯 HTML、CSS 和 JavaScript 管理代码会变得复杂且难以维护。这就是现代前端库如 **React** 发挥作用的地方。
|
||||
>
|
||||
> 
|
||||
>
|
||||
> **[React](https://react.dev/)** 是一个用于构建用户界面的流行 JavaScript 库。它帮助开发者将代码组织成可重用的组件，使得构建和维护复杂的应用程序变得更加容易。
|
||||
>
|
||||
> React 允许你编写管理自己逻辑和外观的组件，然后将它们组合起来构建更大的界面。
|
||||
>
|
||||
> 随着我们的深入，我们将探索更多关于 React 如何工作以及它如何适应我们的工作流程的内容。现在，只需要知道，虽然前端开发通常意味着编写像这样的代码，但我们的工具会自动处理大部分工作——我们只需要知道如何向大语言模型清楚地表达我们的需求！
|
||||
|
||||
# 2. 构建你的第一个游戏
|
||||
|
||||
## 2.1 与 LLM 对话时给出清晰的指令
|
||||
|
||||
在一开始，我们可以用最简单的方式与大模型对话，这将帮助我们快速获得产品原型。我们可以直接在聊天框中输入：
|
||||
|
||||
> **💡 示例提示词：** 帮我做一个贪吃蛇游戏
|
||||
>
|
||||
> 
|
||||
|
||||
> **💡 示例提示词：** 帮我做一个贪吃蛇游戏，它应该支持
|
||||
>
|
||||
> 1. 我可以吃不同的单词，它们会被收集在一个盒子里
|
||||
> 
|
||||
|
||||
> **💡 示例提示词：** 帮我做一个贪吃蛇游戏，它应该支持：
|
||||
>
|
||||
> 1. 我可以吃不同的单词，它们会被收集在一个盒子里
|
||||
> 2. 当蛇吃了8个单词时，llm 应该根据这些单词创作一首诗，我们可以根据需要重新混合这首诗。
|
||||
> 3. 当诗完成后，下一步将自动根据这首诗创建一幅图像。
|
||||
>
|
||||
> 
|
||||
|
||||
## 2.2 尝试修复过程中出现的错误
|
||||
|
||||
在开发过程中，我们可能会遇到不尽如人意的问题，例如点击按钮没有任何反应、使用功能时报错、功能未按预期工作，或者前端页面与预期设计不符。
|
||||
|
||||
在这种情况下，我们需要进一步向模型提问，以帮助修复这些意外问题。
|
||||
|
||||
|
||||
|
||||
## 2.3 如何假装自己是 Vibe Coding 大师
|
||||
|
||||
实际上，在真正的 vibe coding 过程中，我们通常不会使用很多复杂的提示词。也许我们在开始时需要为整个程序提供一个具体且适度复杂的提示词，但在那之后的每一步，你可能只需要以下类型的提示词：
|
||||
|
||||
```JSON
|
||||
"代码里有个 bug，请修复它。"
|
||||
"我不要部分代码，给我完整的修改后的代码。"
|
||||
"你的代码还是有问题。"
|
||||
"请再次修改并给我完整的修正后的代码。"
|
||||
"刚才还能运行，为什么现在不能运行了？"
|
||||
"你没理解我的意思吗？不要改我原来的代码。"
|
||||
"不要添加任何调试功能。"
|
||||
"不要做我没让你做的事。"
|
||||
"我让你实现的功能在哪里？"
|
||||
"你听不懂我说的话吗？"
|
||||
"我只要一个函数。"
|
||||
"我告诉过你参考我之前的代码。"
|
||||
"请不要添加不必要的注释。"
|
||||
"请不要修改我原始代码的基本逻辑。"
|
||||
"帮我修改代码。"
|
||||
"基于我的代码修改..."
|
||||
"不要改我的变量名！！！"
|
||||
"不要改原来的函数名！"
|
||||
"不要乱动我的变量。"
|
||||
"不要添加额外的功能。"
|
||||
"不要只生成框架，生成完整的代码。"
|
||||
```
|
||||
|
||||
这听起来可能有点夸张，但实际上，这些就是我们在日常工作中可能使用的提示词。由于大语言模型的上下文长度限制，或者有时因为它们的指令遵循能力不是很强，模型可能会忘记对话早些时候讨论的内容。
|
||||
|
||||
或者，由于训练数据集的风格，大模型倾向于以其训练数据的风格回答。例如，有些人说话很严肃，有些人喜欢添加很多修饰，而有些大模型喜欢在代码中添加很多注释或不必要的模块。
|
||||
|
||||
这就是为什么我们需要在开始时明确设定界限，例如：不要添加新模块，不要包含太多注释。每个大模型都有自己的风格，我们只能通过实际使用找到我们最喜欢的那个。
|
||||
|
||||
> 💡 什么是模型上下文？
|
||||
>
|
||||
> 模型上下文就像 AI 的 **短期记忆**。它是 AI 记住的当前对话中的所有文本。这使你能够提出后续问题并进行自然的对话，因为 AI “记得”你刚才在谈论什么。没有上下文，你问的每个问题都将是一个全新的、独立的对话。
|
||||
>
|
||||
> 每个模型都有不同的有效上下文长度，通常从 **32k 到 128k** tokens 不等。如果你想让大语言模型一次性阅读一篇很长的文章，或者有许多材料和对话希望 LLM 参考，你可能会发现 LLM 经常忘记长文本中的一些重要内容，或者你可能会注意到对话过程中主题逐渐偏移，这是由上下文限制引起的现象。
|
||||
>
|
||||
> 因此，对于模型，我们也关注上下文。然而，值得注意的是，上下文越长，资源消耗越大，收取的费用也越高。在行业中，有许多压缩上下文的方法，我们将在随后的学习中一一介绍。
|
||||
|
||||
> 💡 什么是指令遵循能力？
|
||||
>
|
||||
> 指令遵循能力指的是 **AI 理解并准确执行你提供的命令的能力**。它不仅仅是回答问题，而是根据你的具体要求完成任务，例如“将这篇文章总结为三个要点”、“用正式的语气写回复”或“翻译这个词并在句子中使用它”。
|
||||
>
|
||||
> 具有强指令遵循能力的模型将完全按照你的指示完成这些操作，而不会执行任何不必要的额外操作。
|
||||
>
|
||||
> 例如，当我们希望 LLM 将一篇文章总结为三个关键点时，我们不希望它给我们五个；当我们希望它从文章中提取某些关键要素（如作者、时间及发生的事件）时，我们不希望它遗漏任何要素。
|
||||
>
|
||||
> 因此，我们希望 LLM 拥有足够强的指令遵循能力，因为这带来了稳定性及 **可复现性**，使它们成为工业应用中的重要组成部分。
|
||||
|
||||
# 3. **使用 API：调用 LLM 和图像生成器**
|
||||
|
||||
## 3.1 什么是 API
|
||||
|
||||
首先，**你需要知道什么是 API** `Extra Knowledge 2 - What is API`
|
||||
|
||||
我们将尝试集成两个 API：一个是调用 DeepSeek LLM，另一个是调用 Seedream (即梦) 模型。这两个模型都很棒，性能出色。
|
||||
|
||||
在使用 API 的过程中，只有两个最重要的元素：
|
||||
|
||||
1. API key (密钥)
|
||||
2. 官方文档示例
|
||||
|
||||
只要你能找到这两个，你就可以让 LLM 帮你修改并实现所有类型的 API 调用。
|
||||
|
||||
## 3.2 将 DeepSeek API 集成到 z.ai 中
|
||||
|
||||
### 什么是 DeepSeek
|
||||
|
||||
|
||||
|
||||
> 📚 信息引用自 [DeepSeek Wiki](https://en.wikipedia.org/wiki/DeepSeek)
|
||||
>
|
||||
> **杭州深度求索人工智能基础技术研究有限公司**（**Hangzhou DeepSeek Artificial Intelligence Basic Technology Research Co., Ltd.**），以 **DeepSeek** 为商号，是一家开发大语言模型（LLMs）的中国人工智能（AI）公司。DeepSeek 总部位于浙江杭州，由中国对冲基金幻方量化（High-Flyer）拥有并资助。DeepSeek 由幻方量化的联合创始人梁文锋于 2023 年 7 月创立，他也同时担任这两家公司的 CEO。该公司于 2025 年 1 月推出了同名聊天机器人及其 DeepSeek-R1 模型。
|
||||
>
|
||||
> 让我们看看 DeepSeek 在 GPQA 基准排名中与其他顶级模型的表现对比。值得注意的是，DeepSeek 是一个开源（每个人都可以从互联网下载模型）模型，而其他常见模型如 Grok、Google Gemini 和 ChatGPT 都是闭源的。正如我们所见，DeepSeek 已经很大程度上接近了第一梯队的模型。
|
||||
>
|
||||
> 
|
||||
>
|
||||
> GPQA 是“研究生级 Google-Proof 问答基准”的缩写，这是一个用于科学问答任务的研究生级基准。以下是详细介绍。
|
||||
>
|
||||
> GPQA 包含 448 个多项选择题，涵盖生物学、物理学和化学的子领域，如量子力学、有机化学、分子生物学等。这些问题由 61 位持有博士学位或正在攻读博士学位的专家编写，并经过了严格的验证过程。
|
||||
|
||||
### 如何获取 deepseek API
|
||||
|
||||
我们将尝试根据我们已有的信息，让 z.ai 直接将 DeepSeek API 集成到项目中。
|
||||
|
||||
首先，我们需要在 DeepSeek 开放平台注册一个账户。
|
||||
|
||||
https://platform.deepseek.com/sign_up
|
||||
|
||||
然后，你会看到像这样的网页界面：
|
||||
|
||||
|
||||
|
||||
要使用 API，我们需要先充值 token。10 元人民币足够使用一段时间了！
|
||||
|
||||
|
||||
|
||||
点击“API KEYS”并在屏幕下方找到“create new API key”。你最终会得到一个像 `sk-8573341c39fc44315aadc071c53rh7d2` 这样的 API key。
|
||||
|
||||
|
||||
|
||||
一旦你获得了密钥，你就拥有了调用模型的权限。
|
||||
|
||||
此时，你可以直接阅读 [API 文档](https://api-docs.deepseek.com/)，它通常提供 curl 或 Python 的调用示例。
|
||||
|
||||
|
||||
|
||||
找到示例后，你可以将文档中与密钥相关的所有内容复制到 z.ai，并要求它尝试帮你集成 LLM。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
自动集成可以在很短的时间内完成。我们可以询问它的操作员确认 DeepSeek API 是否已经在使用中。
|
||||
|
||||
|
||||
|
||||
或者，我们可以要求 z.ai 帮我们定位项目中调用 LLM 的部分。
|
||||
|
||||
然后我们可以独立确认是否正在使用 DeepSeek。具体来说，我们可以直接请求：`"告诉我项目中所有需要调用 LLM 的代码位置，我需要检查是否是 DeepSeek。"`，z.ai 将返回所有 API 调用的详细地址。
|
||||
|
||||
|
||||
|
||||
接下来，我们将简要介绍目前可用的三种最先进的图像生成模型。你可以根据自己的喜好选择一种集成到 z.ai 中。
|
||||
|
||||
## 3.3 将 SiliconFlow QwenImage API 集成到 z.ai 中
|
||||
|
||||
### 什么是 SiliconFlow
|
||||
|
||||
> [Silicon Flow (硅基流动)](https://cloud.siliconflow.com/me/models) 成立于 2023 年 8 月，是一家世界领先的 AI 能力提供商。它提供 SiliconCloud（具有自研推理加速的大模型云平台）和 BizyAir（用于 AI 图像生成的 ComfyUI 插件）等核心产品，为客户提供 AI 基础设施能力，拥有战略合作伙伴关系，并持有顶级行业认证。
|
||||
>
|
||||
> 
|
||||
|
||||
### 什么是 QwenImage
|
||||
|
||||
> Qwen-Image 是一个强大的图像生成基础模型，能够进行复杂的文本渲染和精确的图像编辑。这是一个 20B MMDiT 图像基础模型，在复杂的文本渲染和精确的图像编辑方面取得了重大进展。实验表明，它在图像生成和编辑方面都具有很强的通用能力，在文本渲染方面表现尤为出色，尤其是中文。
|
||||
>
|
||||
> 从中文到英文，QwenImage 可以像 GPT-4o 或 Seedream 模型一样生成高质量的文本。
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 
|
||||
|
||||
### 如何获取 SiliconFlow QwenImage API
|
||||
|
||||
https://cloud.siliconflow.com/me/models
|
||||
|
||||
查看 SiliconFlow 的官网。左侧有一个“Playground”部分，你可以在不进行 API 调用的情况下试用不同的模型。在网页顶部有一个“Filters”按钮；点击它可以筛选右侧的模型列表。
|
||||
|
||||
如果你选择“Image”，你将只看到当前支持的所有文生图模型。在这种情况下，我们将使用 Qwen/Qwen-Image。
|
||||
|
||||
|
||||
|
||||
要调用 API，首先我们需要点击左侧设置中的“API Keys”，然后点击“Create API Key”按钮生成一个 API key。记得保存这个 API key。
|
||||
|
||||
|
||||
|
||||
要查看可用余额，我们需要打开左侧设置中的“Payments”。在这里，你可以看到 1 美元的赠金。但是，如果你想使用 FLUX 文生图模型，你需要先充值账户。
|
||||
|
||||
https://cloud.siliconflow.com/me/account/ak
|
||||
|
||||
|
||||
|
||||
一切设置好后，我们需要参考相应的图像生成 API 文档。你可以在官方文档页面找到任何标记为“API Reference”的部分。点击它，然后导航到图像生成的 API 端点部分并找到相关的请求示例。
|
||||
|
||||
https://docs.siliconflow.com/en/userguide/introduction
|
||||
|
||||
|
||||
|
||||
```Bash
|
||||
curl --request POST \
|
||||
--url https://api.siliconflow.com/v1/images/generations \
|
||||
--header 'Authorization: Bearer <token>' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"model": "black-forest-labs/FLUX.1-Kontext-max",
|
||||
"prompt": "an island near sea, with seagulls, moon shining over the sea, light house, boats int he background, fish flying over the sea"
|
||||
}'
|
||||
```
|
||||
|
||||
记得将你打算使用的模型和 API key 填入相应的字段。之后，你可以在计算机的命令行中使用该命令运行直接请求测试。
|
||||
|
||||
```Bash
|
||||
curl --request POST \
|
||||
--url https://api.siliconflow.com/v1/images/generations \
|
||||
--header 'Authorization: Bearer sk-defrgqrgrganpncxxibfyzfocgafga' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"model": "Qwen/Qwen-Image",
|
||||
"prompt": "an island near sea, with seagulls, moon shining over the sea, light house, boats int he background, fish flying over the sea"
|
||||
}'
|
||||
```
|
||||
|
||||
|
||||
|
||||
你可以将下面修改后的代码行发送给 z.ai，并要求它帮你创建一个前端测试演示。很快，你就能实现 SiliconFlow 的基本 API 调用。
|
||||
|
||||
|
||||
|
||||
## 3.4 将 Recraft API 集成到 z.ai 中
|
||||
|
||||
### 什么是 Recraft
|
||||
|
||||
> Recraft 是一款面向设计师、插画师和营销人员的 AI 工具——于 2022 年在美国成立，总部位于伦敦。它帮助生成/迭代视觉效果（图像、矢量艺术、3D 图形），具有高质量输出（任何文本大小/长度）、精确元素定位和品牌一致性设计等优势。受到 200 个国家/地区 300 多万用户（包括奥美、Netflix）的信任，并已创建了 3.5 亿多张图像，其团队旨在使其成为必备的设计师工具，确保创作者能够控制他们的 AI 辅助工作流程。
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 
|
||||
|
||||
### 如何获取 Recraft API
|
||||
|
||||
首先，我们仍然需要找到重要的 API 入口以获取我们的 API key。 https://www.recraft.ai/profile/api
|
||||
|
||||
由于这里没有提供免费额度，我们需要自己充值 1,000 积分。这个网站支持支付宝和微信支付，所以很容易获得 1,000 积分（注意：不要充值超过必要的金额）。
|
||||
|
||||
|
||||
|
||||
之后，我们仍然遵循通常的方法：去官方文档找到相应的请求示例。
|
||||
|
||||
https://www.recraft.ai/docs/api-reference/getting-started
|
||||
|
||||
https://www.recraft.ai/docs/api-reference/usage
|
||||
|
||||
https://www.recraft.ai/docs/api-reference/guides
|
||||
|
||||
在这里，我们可以直接复制整个内容并粘贴到 z.ai。
|
||||
|
||||
|
||||
|
||||
注意，在聊天窗口中，输入你的 API key 和文档内容就足够了；z.ai 会自动为你构建前端。
|
||||
|
||||
如果过程中出现错误，你可以直接将错误信息粘贴到聊天窗口，让 z.ai 帮你自动解决。
|
||||
|
||||
|
||||
|
||||
## 3.5 将 Seedream API 集成到 z.ai 中（针对中国用户）
|
||||
|
||||
### 什么是 Seedream 4.0
|
||||
|
||||
https://seed.bytedance.com/en/seedream4_0
|
||||
|
||||
|
||||
|
||||
> 也许你已经知道 Nano Banana（Google 开发），但你最好不要错过 Seedream。Seedream 4.0 是字节跳动打造的新一代图像创作模型。它将图像生成和图像编辑能力集成到一个统一的架构中。这使得它能够灵活处理复杂的多模态任务，如基于知识的生成、复杂推理和参考一致性。此外，它的推理速度比前代产品快得多，并且可以生成分辨率高达 4K 的令人惊叹的高清图像。
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 
|
||||
>
|
||||
> 
|
||||
|
||||
### 如何获取 Seedream API - 火山引擎 (Volcengine)（针对中国用户）
|
||||
|
||||
我们将逐步演示如何将 Seedream API 集成到 z.ai 示例中。
|
||||
|
||||
https://www.volcengine.com/experience/ark?launch=seedream
|
||||
|
||||
访问页面后，点击登录。
|
||||
|
||||
|
||||
|
||||
登录后，找到页面右上角的充值选项。
|
||||
|
||||
|
||||
|
||||
进行充值需要实名认证。
|
||||
|
||||
|
||||
|
||||
认证成功后，你可以充值 1 元用于测试。
|
||||
|
||||
https://console.volcengine.com/finance/fund/recharge
|
||||
|
||||
|
||||
|
||||
返回初始界面并点击 API 访问。
|
||||
|
||||
|
||||
|
||||
首先，创建一个 API key，然后点击选择选项。
|
||||
|
||||
|
||||
|
||||
这将带你进入第 2 步。在这里，你需要确认调用的服务是 Seedream 4.0，并复制提供的调用示例。
|
||||
|
||||
|
||||
|
||||
准备好 API key 和调用示例后，你可以直接将它们粘贴到 z.ai 中以生成前端交互演示。
|
||||
|
||||
重要提示：这里的默认示例相对复杂。记得禁用“添加水印”选项和“流式响应”选项，以确保不生成水印且不会发生请求失败。
|
||||
|
||||
|
||||
|
||||
输入提示词后，你将收到生成的结果。享受它吧！
|
||||
|
||||
|
||||
|
||||
# 让它更有趣
|
||||
|
||||
完成基本功能后，我们可以尝试给我们的程序添加一些新花样！如果你觉得蛇吃单词或字符的过程有点枯燥，你可以让蛇吃不同颜色的单词，并相应地改变蛇的颜色。
|
||||
|
||||
你还可以为“吃”的过程添加特效，或者引入触发特效的魔法单词——比如增加蛇的速度或大小。另一个想法是每当蛇吃一个单词时就让模型生成一首诗和一幅图，而不是等到它吃掉八个单词。
|
||||
|
||||
如果觉得这些有挑战性，你可以直接向语言模型求助！它可以提供创意建议，让你的游戏更有趣。试一试吧！
|
||||
|
||||
```JavaScript
|
||||
1. "单词解锁世界" 机制
|
||||
每当蛇吃掉一个单词，LLM 会对该单词进行诗意联想（例如，“树”→“森林”、“绿荫”），图像模型会即时为该单词生成一个小艺术品。这些图像逐渐拼凑成一个独特的、玩家创造的全景图，所以玩家每次游玩都在“作画和写诗”。
|
||||
|
||||
2. "诗歌拼图" 玩法
|
||||
蛇吃掉的每个单词都会触发 LLM 生成简短的诗句，图像模型生成插图。这些诗句和图像像拼图一样组合在一起，在回合结束时形成一首 AI 协作的诗和画。
|
||||
|
||||
3. "魔法单词" & "故事分支"
|
||||
特殊的“魔法单词”（例如，“风”、“夜”、“梦”）不仅触发 LLM 生成诗歌，还会改变场景的情绪或主题——将生成图像的风格转变为夜晚、暴风雨或梦幻般的氛围。
|
||||
分支故事：LLM 在开始时给出一个主题或谜语（例如，“秋天的回忆”）。玩家的单词选择直接影响故事和诗歌的演变，图像模型实时更新背景和视觉效果。
|
||||
|
||||
4. "实时互动生成"
|
||||
每个单词之后，LLM 生成一行对话或描述，游戏中的 NPC 可以对玩家“说话”，或者环境可以相应地改变。
|
||||
蛇的外观或游戏中的障碍物可以根据吃掉的单词在视觉上发生变化，这要归功于图像模型。
|
||||
|
||||
5. "创作 & 分享"
|
||||
玩家可以在会话结束时保存并分享他们 AI 创作的诗歌和图像，炫耀他们独特的“AI 协作”。
|
||||
“最美诗歌+艺术”、“最有创意单词组合”等排行榜，鼓励重玩和创造力。
|
||||
|
||||
6. "按句贪吃蛇" 挑战
|
||||
反向模式：LLM 给出一句诗或一个谜语，玩家必须引导蛇按顺序吃掉单词来重构句子。吃错单词会通过图像生成模型触发有趣或艺术性的后果。
|
||||
|
||||
7. "主题关卡" & "风格选择"
|
||||
游戏开始时，玩家选择一个主题（例如，“童话”、“科幻”、“唐诗”），LLM 和图像模型都会调整单词选择、诗歌风格和视觉效果以匹配，使每次运行都感觉新鲜。
|
||||
|
||||
8. "现场共创"
|
||||
当吃掉一个特殊单词时，LLM 可以提示玩家输入短语或选择风格，然后 AI 生成相应的诗句和插图，使其成为真正的人类-AI 共创。
|
||||
|
||||
9. "AI 彩蛋 & 成就"
|
||||
某些单词组合被 LLM 识别为特殊主题或内部笑话（例如，“月亮”、“桂花”、“河岸”），触发稀有的诗句和插图，奖励探索。
|
||||
|
||||
10. "成长的故事"
|
||||
随着蛇的成长，LLM 生成一个连续的故事诗，图像模型创建一个无缝的长卷或全景图，所以玩家同时在“写作、绘画和玩耍”。
|
||||
```
|
||||
|
||||
此外，我们还可以要求 LLM 帮你直接生成项目级的提示词。在上一节中，我们只自己写了贪吃蛇游戏的提示词。现在让我们尝试让大模型生成一个带有整体框架和实现路径的提示词（你可以直接用 z.ai 生成）：
|
||||
|
||||
> 我想让 AI 生成一个网页贪吃蛇游戏，需要一个更完整的提示词，让生成结果更令人印象深刻和有趣。请生成相应的提示词。当前目标是：生成一个贪吃蛇游戏，需要实现吃不同单词生成诗歌的功能，并且应该包含图像生成模块。
|
||||
|
||||
z.ai 的回复将会是这样的：
|
||||
|
||||
|
||||
|
||||
我们可以使用这个提示词在全栈开发模式下重新生成项目：
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# 更多参考案例
|
||||
|
||||
除了贪吃蛇（游戏），我们可以让想象力尽情驰骋。
|
||||
|
||||
创造任何我们想创造的东西，甚至尝试搞砸一切！然后重头再来！
|
||||
|
||||
```YAML
|
||||
1. AI 艺术画廊平台
|
||||
描述：一个展示 AI 生成艺术作品的在线画廊，用户可以上传、分享和评论 AI 艺术作品。
|
||||
功能：用户账户系统、艺术作品上传和展示、评分系统、分类浏览、AI 生成工具集成。
|
||||
技术亮点：React/Vue 前端、Node.js 后端、MongoDB 数据库、AI API 集成。
|
||||
|
||||
2. 复古游戏档案馆
|
||||
描述：一个致敬经典游戏的网站，包含游戏历史、玩法指南和在线可玩复古游戏。
|
||||
功能：游戏数据库、时间轴展示、在线模拟器、用户评论、游戏收藏功能。
|
||||
技术亮点：响应式设计、WebGL/Canvas 游戏实现、RESTful API、用户认证系统。
|
||||
|
||||
3. 可持续生活追踪器
|
||||
描述：一个帮助用户通过环保提示和社区挑战来追踪和减少碳足迹的网站。
|
||||
功能：个人碳足迹计算器、目标设定、进度追踪、社区挑战、环保知识库。
|
||||
技术亮点：数据可视化、移动端优化、社交功能、推送通知。
|
||||
|
||||
4. 虚拟厨房助手
|
||||
描述：一个基于 AI 的烹饪指导平台，提供个性化食谱推荐和分步烹饪说明。
|
||||
功能：食谱数据库、食材识别、个性化推荐、烹饪计时器、营养分析。
|
||||
技术亮点：图像识别 API、机器学习推荐系统、语音控制、实时视频指导。
|
||||
|
||||
5. 地下音乐发现平台
|
||||
描述：一个专注于独立和新兴艺术家的音乐流媒体平台，提供独特的发现体验。
|
||||
功能：音乐流媒体、艺术家资料、个性化推荐、播放列表创建、社区评论。
|
||||
技术亮点：音频流处理、推荐算法、社交功能、音乐可视化。
|
||||
|
||||
6. 极简任务管理系统
|
||||
描述：一个具有禅意美学的任务管理工具，专注于简单和高效的任务组织。
|
||||
功能：任务创建和分类、优先级设置、进度追踪、团队协作、数据分析。
|
||||
技术亮点：极简 UI 设计、拖放功能、实时同步、跨平台兼容性。
|
||||
|
||||
7. 科幻写作工坊
|
||||
描述：一个为科幻作家提供创意工具和灵感的平台，包括世界观构建辅助和角色开发工具。
|
||||
功能：故事结构工具、角色资料、世界观构建模板、写作统计、社区反馈。
|
||||
技术亮点：富文本编辑器、数据可视化、协作编辑、AI 辅助创作。
|
||||
|
||||
8. 个人知识图谱
|
||||
描述：一个帮助用户构建个人知识网络，可视化并连接各种想法和信息的工具。
|
||||
功能：节点创建和连接、标签系统、搜索功能、导入/导出工具、可视化图表。
|
||||
技术亮点：图数据库、数据可视化算法、Markdown 支持、跨设备同步。
|
||||
|
||||
9. 虚拟植物园
|
||||
描述：一个互动植物百科全书，用户可以探索植物世界并创建虚拟花园。
|
||||
功能：植物数据库、3D 植物模型、生长模拟、园艺指南、社区展示。
|
||||
技术亮点：3D 渲染、季节变化模拟、AR 集成、植物识别 API。
|
||||
|
||||
10. 编程挑战竞技场
|
||||
描述：一个面向程序员的在线竞赛平台，具有各种难度级别的编程挑战。
|
||||
功能：挑战问题、代码编辑器、自动评估、排行榜、学习路径。
|
||||
技术亮点：代码沙箱环境、实时评估系统、算法可视化、社交学习功能。
|
||||
```
|
||||
|
||||
还有... 如果你喜欢玩游戏，让我们一起尝试创造游戏吧！
|
||||
|
||||
```SQL
|
||||
1. 3D 开放世界 RPG
|
||||
描述：一个具有广阔开放世界、任务和角色成长的奇幻 RPG。
|
||||
功能：昼夜循环、动态天气、技能树、多人合作、制作系统。
|
||||
技术亮点：Three.js 或 Babylon.js 用于 3D 渲染、服务器端游戏逻辑、角色自定义、存档系统。
|
||||
|
||||
2. 第一人称射击 (FPS) 竞技场
|
||||
描述：一个快节奏的多人 FPS，具有各种游戏模式和地图。
|
||||
功能：团队死斗、夺旗、武器自定义、排位赛。
|
||||
技术亮点：WebGL/Three.js 用于 3D 图形、多人网络代码、命中检测、语音聊天。
|
||||
|
||||
3. AI 国际象棋和多人游戏
|
||||
描述：一个功能齐全的国际象棋平台，具有 AI 对手和在线对战功能。
|
||||
功能：AI 难度级别、残局挑战、锦标赛模式、回放分析。
|
||||
技术亮点：国际象棋逻辑库、WebSocket 用于实时对战、ELO 排名系统、反作弊。
|
||||
|
||||
4. 麻将在线多人游戏
|
||||
描述：一个具有在线多人游戏和计分功能的传统麻将游戏。
|
||||
功能：多种规则集、私人房间、排名系统、回放功能。
|
||||
技术亮点：牌匹配逻辑、实时多人游戏、大厅系统、分数追踪。
|
||||
|
||||
5. 回合制策略游戏
|
||||
描述：一个具有网格战斗和单位管理的战术策略游戏。
|
||||
功能：战役模式、遭遇战、单位升级、战争迷雾、多人对战。
|
||||
技术亮点：网格移动系统、AI 决策、回合同步、存档/读档系统。
|
||||
|
||||
6. 计时赛赛车游戏
|
||||
描述：一个专注于计时赛和赛道记录的 3D 赛车游戏。
|
||||
功能：多条赛道、汽车自定义、幽灵回放、排行榜。
|
||||
技术亮点：3D 汽车物理、赛道编辑器、回放系统、在线排行榜。
|
||||
|
||||
7. 卡牌对战游戏 (卡组构建)
|
||||
描述：一个策略卡牌游戏，玩家构建卡组并与对手战斗。
|
||||
功能：卡牌收集、卡组构建、排位赛、赛季活动。
|
||||
技术亮点：卡牌游戏逻辑、匹配系统、AI 对手、卡牌动画。
|
||||
|
||||
8. 大逃杀 (俯视 2D)
|
||||
描述：一个俯视 2D 大逃杀游戏，具有缩小的游戏区域和战利品机制。
|
||||
功能：单人和小队模式、武器多样性、局内事件、排行榜。
|
||||
技术亮点：实时多人游戏、区域缩小逻辑、战利品生成系统、匹配。
|
||||
|
||||
9. 恐怖生存游戏 (第一人称)
|
||||
描述：一个具有资源管理和逃生机制的第一人称恐怖游戏。
|
||||
功能：氛围环境、解谜、敌人 AI、多重结局。
|
||||
技术亮点：动态照明、声音设计、敌人寻路、存档系统。
|
||||
|
||||
10. 音乐节奏游戏 (3D)
|
||||
描述：一个 3D 节奏游戏，玩家随着音乐节拍击打音符。
|
||||
功能：多种难度级别、赛道编辑器、自定义歌曲支持、排行榜。
|
||||
技术亮点：音频分析、节拍同步、3D 音符轨道、输入时机检测。
|
||||
```
|
||||
|
||||
# 总结
|
||||
|
||||
这就是完整的教程！你可能需要 **4 小时** 才能完成所有内容并构建你自己的贪吃蛇游戏。不要着急——探索、实验并享受这个过程。
|
||||
|
||||
如果你有不同的游戏想法，那也很好。最重要的是开始构建。
|
||||
|
||||
祝你好运，欢迎来到 AI 原生创造力的世界 :)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.1 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 64 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 107 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 379 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 373 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 656 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 318 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 283 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 119 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 127 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 108 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 223 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 385 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 299 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 98 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 268 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 167 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 640 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 MiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user