150 lines
5.4 KiB
Markdown
150 lines
5.4 KiB
Markdown
<div align="center">
|
||
|
||
<h2>🚀 All-in-RAG · Extra Chapter</h2>
|
||
|
||
<p><em>主教程之外的「知识拓展与社区实践」专区</em></p>
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 📖 Extra Chapter 是什么？
|
||
|
||
`Extra-chapter` 目录用于存放 **不直接属于主线章节，但对 RAG / LLM 应用非常有价值的补充内容**。这些内容可以是你对某个相关技术（如 Neo4j、Milvus、GraphRAG 等）的系统整理，也可以是与你的研究/工作紧密相关的专题总结。
|
||
|
||
在主仓库的「知识拓展」部分，我们会以清单形式挂出这里的优秀专题，例如：
|
||
|
||
- `Neo4J 简单应用`（本目录下的第一个示例专题）
|
||
- `PowerRAG SDK 文本检索 Demo`（上传 Markdown → 解析/切分/向量化 → Top‑K 检索）
|
||
|
||
我们希望通过 Extra Chapter：
|
||
|
||
- **补充主教程**：覆盖 RAG 周边的生态组件和工程化话题
|
||
- **沉淀实践经验**：记录真实项目中的设计思路与解决方案
|
||
- **鼓励多元视角**：允许不同风格的探索与实验性内容
|
||
- **形成可引用的知识单元**：每个专题都可以被单独阅读和复用
|
||
|
||
---
|
||
|
||
## 📂 推荐目录结构
|
||
|
||
每一个新专题建议在 `Extra-chapter/` 下新建一个独立子目录，并至少包含一个 `readme.md` 作为主文档。参考结构如下（可按需要增减）：
|
||
|
||
```text
|
||
Extra-chapter/
|
||
├── your-topic-name/ # 你的专题目录（必需）
|
||
│ ├── readme.md # 专题主文档（必需）
|
||
│ ├── images/ # 图片资源（建议有图片时使用）
|
||
│ │ ├── figure1.png
|
||
│ │ └── figure2.jpg
|
||
│ ├── code/ # 代码示例（如有代码建议单独放）
|
||
│ │ ├── demo.py
|
||
│ │ └── requirements.txt
|
||
│ └── data/ # 示例数据（如有）
|
||
│ └── sample_data.json
|
||
└── README.md # 本说明文件
|
||
```
|
||
|
||
> 当前仓库中的 `Neo4J 简单应用` 专题位于 `Extra-chapter/Neo4J/readme.md`，你可以参考其组织方式，但不必完全照搬。
|
||
|
||
---
|
||
|
||
## 🧱 命名与排版建议
|
||
|
||
### 1. 目录与文件命名
|
||
|
||
- **专题目录名 (`your-topic-name/`)**
|
||
- 使用有语义的英文或中英文混合
|
||
- 避免过长，尽量能一眼看出主题，例如：
|
||
- `Neo4J-Simple-Application`
|
||
- `graph-rag-practice`
|
||
|
||
- **主文档**
|
||
- 固定为：`readme.md`（小写），便于 GitHub 直接展示
|
||
|
||
- **图片 / 代码 / 数据**
|
||
- 统一放在 `images/`、`code/`、`data/` 等子目录中
|
||
- 文件名建议包含用途或内容关键信息，例如：`pipeline-overview.png`、`retriever_benchmark.ipynb`
|
||
|
||
### 2. 内容组织与标题层级
|
||
|
||
推荐的章节骨架（可根据需要微调）：
|
||
|
||
- `# 专题标题`
|
||
- `## 背景与动机`
|
||
- `## 场景或问题描述`
|
||
- `## 技术方案 / 实现思路`
|
||
- `## 实践步骤 / 代码示例`
|
||
- `## 经验总结与坑点`
|
||
|
||
标题层级请保持清晰，避免过多嵌套（一般不超过三级：`##` / `###` / `####`）。
|
||
|
||
---
|
||
|
||
## ✅ 内容质量与范围
|
||
|
||
为了让内容对读者真正有帮助，提交 PR 前请尽量满足以下要求：
|
||
|
||
- **与 RAG / LLM 应用相关**
|
||
- 例如：图数据库在 RAG 中的用法、检索评估方案、多模态扩展、部署/监控经验等
|
||
|
||
- **技术与事实尽量准确**
|
||
- 如有推测或实验性的结论，请明确标注
|
||
- 关键代码建议给出可运行环境说明（Python 版本、依赖库等）
|
||
|
||
- **结构清晰、可独立阅读**
|
||
- 读者不看主教程，也能从该专题收获完整的一段知识
|
||
|
||
- **尊重版权与引用规范**
|
||
- 如引用论文、博客或开源项目，请在文末列出参考资料或链接
|
||
|
||
---
|
||
|
||
## 🔀 提交 PR 的具体步骤（建议）
|
||
|
||
1. **Fork 仓库并创建分支**
|
||
- 从 `main` 或当前默认分支拉出个人分支，例如：`feat/extra-chapter-neo4j-practice`
|
||
|
||
2. **在 `Extra-chapter/` 下创建你的专题目录**
|
||
- 遵循上文的目录组织方案
|
||
- 如有需要，可在根目录 `README.md` 的「第六部分：知识拓展」列表中，添加指向你专题的链接（格式参考已有的 `Neo4J 简单应用`）
|
||
|
||
3. **本地检查排版与图片路径**
|
||
- 确认 Markdown 渲染正常、图片路径相对位置正确
|
||
|
||
4. **编写有信息量的 Commit Message**
|
||
|
||
推荐包含以下信息（可按实际场景调整）：
|
||
|
||
```text
|
||
Extra-chapter: <你的专题标题>
|
||
|
||
- 新增专题目录：Extra-chapter/<your-topic-name>
|
||
- 主要内容：简要说明该专题解决了什么问题 / 分享了哪些经验
|
||
- 代码与数据：如有，说明放在哪些子目录，如何运行
|
||
- 个人信息（可选但推荐）：你的 GitHub 链接、研究 / 工作方向等
|
||
```
|
||
|
||
5. **发起 PR**
|
||
- PR 标题中建议包含：`[Extra-chapter]` + 你的专题名
|
||
- 在 PR 描述里可以：
|
||
- 说明该专题与 All-in-RAG 主线章节的关系
|
||
- 标注阅读顺序建议（例如：适合在读完第 3 章之后再看）
|
||
|
||
---
|
||
|
||
## 💬 沟通与反馈
|
||
|
||
如果你在撰写 Extra Chapter 的过程中：
|
||
|
||
- 不确定选题是否合适
|
||
- 想讨论目录设计或技术路线
|
||
- 希望对草稿先做一次技术性 Review
|
||
|
||
可以在仓库的 `Discussions` 或 `Issues` 中发起话题，标题中带上 `Extra-chapter` 关键字，方便维护者和其他贡献者一起参与讨论。
|
||
|
||
---
|
||
|
||
欢迎你把自己的实践经验沉淀在这里，让更多学习 RAG / LLM 应用的同学受益。 🎉
|
||
|