开源大模型食用指南

主题

贡献指南 ​

感谢您对开源大模型食用指南项目的关注！本文档将指导您如何向项目贡献代码、文档或提出建议。

贡献方式 ​

您可以通过以下方式为项目做出贡献：

  • 🐛 提交 Issue 报告 Bug 或提出新功能建议
  • 📝 提交 Pull Request 贡献代码或文档
  • 📚 完善现有教程，修正错误
  • 🆕 添加新模型的部署和微调教程
  • 💬 参与讨论，帮助其他用户解决问题

提交 Issue ​

Issue 是报告问题、提出建议或讨论新功能的最佳方式。

如何提交 Issue ​

  1. 访问项目的 GitHub Issues 页面
  2. 点击 New issue 按钮
  3. 选择合适的 Issue 模板（Bug Report / Feature Request）
  4. 填写标题和详细描述
  5. 添加相关标签（bug、enhancement、documentation 等）
  6. 点击 Submit new issue

提交 Issue 示意图

Issue 内容建议 ​

报告 Bug：

  • 问题的详细描述
  • 复现步骤
  • 预期行为 vs 实际行为
  • 环境信息（操作系统、Python 版本、依赖版本）
  • 相关的错误日志或截图

功能建议：

  • 功能的详细描述
  • 使用场景和动机
  • 可能的实现方案
  • 相关参考资料

提交 Pull Request ​

Pull Request（PR）是贡献代码或文档的方式。

完整 PR 流程 ​

1. Fork 仓库 ​

访问项目主页，点击右上角的 Fork 按钮，将仓库 Fork 到你的 GitHub 账号下。

2. 克隆 Fork 的仓库 ​

bash
# 克隆你 Fork 的仓库到本地
git clone https://github.com/YOUR-USERNAME/self-llm.git

# 进入项目目录
cd self-llm

# 添加上游仓库
git remote add upstream https://github.com/datawhalechina/self-llm.git

# 验证远程仓库
git remote -v

3. 创建新分支 ​

bash
# 创建并切换到新分支
git checkout -b feature/your-feature-name

# 或者修复 bug 的分支
git checkout -b fix/your-bug-fix

分支命名建议

  • 新功能：feature/model-name-tutorial
  • Bug 修复：fix/issue-number-description
  • 文档更新：docs/update-readme

4. 进行修改 ​

在本地进行代码或文档的修改。

添加新模型教程的标准结构：

models/
└── YourModel/
    ├── 01-YourModel-FastApi部署调用.md
    ├── 02-YourModel-langchain接入.md
    ├── 03-YourModel-WebDemo部署.md
    ├── 04-YourModel-Lora微调.md
    ├── images/                     # 教程中使用的图片
    └── 参考代码/                   # 代码示例
        ├── api.py
        ├── web_demo.py
        └── requirements.txt

5. 提交更改 ​

bash
# 查看修改状态
git status

# 添加修改的文件
git add .

# 或添加特定文件
git add models/YourModel/

# 提交更改
git commit -m "feat: add YourModel deployment tutorial"

提交信息规范

使用语义化的提交信息：

  • feat: 新功能
  • fix: Bug 修复
  • docs: 文档更新
  • style: 代码格式调整
  • refactor: 代码重构
  • test: 测试相关
  • chore: 构建/工具相关

6. 推送到 Fork 仓库 ​

bash
# 推送到你的 Fork 仓库
git push origin feature/your-feature-name

如果遇到连接问题，可以使用 SSH：

bash
git remote set-url origin git@github.com:YOUR-USERNAME/self-llm.git
git push origin feature/your-feature-name

7. 创建 Pull Request ​

  1. 访问你的 Fork 仓库页面
  2. 点击 Pull requests 标签
  3. 点击 New pull request 按钮
  4. 确保选择正确的分支：
    • base: datawhalechina/self-llm master
    • compare: YOUR-USERNAME/self-llm feature/your-feature-name
  5. 填写 PR 标题和描述：
    • 简洁明了的标题
    • 详细的修改说明
    • 相关的 Issue 编号（如：Closes #123）
    • 测试方法和结果
  6. 点击 Create pull request

创建 PR 流程

PR 审核流程 ​

  1. 项目维护者会审查你的 PR
  2. 如需修改，维护者会留下评论
  3. 根据反馈进行修改：
    bash
    # 在原分支上继续修改
git add .
git commit -m "fix: address review comments"
git push origin feature/your-feature-name
  4. PR 通过审核后会被合并到主分支

同步上游更新 ​

在开发过程中，保持 Fork 仓库与上游仓库同步：

bash
# 获取上游仓库的更新
git fetch upstream

# 切换到 master 分支
git checkout master

# 合并上游的 master 分支
git merge upstream/master

# 推送到你的 Fork 仓库
git push origin master

图形界面操作（GitHub 网页） ​

如果不熟悉命令行，可以直接在 GitHub 网页上操作。

创建文件夹 ​

  1. 在 Fork 的仓库中点击 Add file → Create new file
  2. 在文件名处输入 folder-name/readme.md
  3. 输入 / 会自动创建文件夹
  4. 编辑内容后提交

网页创建文件夹

上传文件 ​

  1. 进入目标文件夹
  2. 点击 Add file → Upload files
  3. 拖拽或选择文件上传
  4. 填写提交信息并提交

删除文件 ​

  1. 打开要删除的文件
  2. 点击右上角的三个点（···）
  3. 选择 Delete file
  4. 填写提交信息并确认

内容贡献规范 ​

教程文档规范 ​

  1. 结构完整：包含环境准备、代码实现、运行结果、常见问题
  2. 代码可运行：提供完整的、可直接运行的代码示例
  3. 配图清晰：关键步骤配有截图，图片大小适中
  4. 注明贡献者：在文档末尾注明 @your-name
  5. 中文为主：教程使用中文编写，代码注释也使用中文

代码规范 ​

  1. 符合 PEP 8：Python 代码遵循 PEP 8 规范
  2. 添加注释：关键代码添加中文注释
  3. 依赖明确：提供 requirements.txt 文件
  4. 路径统一：使用相对路径或配置文件管理路径

数据集规范 ​

  1. 使用项目统一的数据集（如 dataset/huanhuan.json）
  2. 如需添加新数据集，说明数据来源和格式
  3. 注意数据集的版权和使用许可

核心贡献者 ​

项目核心贡献者享有以下权限：

  • 直接提交代码到主分支（谨慎使用）
  • 审核和合并 PR
  • 管理 Issue 和标签
  • 参与项目方向讨论

如果您有意成为核心贡献者，请联系项目负责人：

  • 宋志学（不要葱姜蒜）
  • 邹雨衡（Logan Zou）

贡献者激励 ​

  • 所有贡献者会在 README.md 中署名
  • 优秀贡献者会被推荐为 Datawhale 成员
  • 持续贡献者有机会成为项目核心维护者
  • 贡献量统计在 contributors.json 中

常见问题 ​

Fork 后如何更新？ ​

定期同步上游仓库，避免冲突：

bash
git fetch upstream
git checkout master
git merge upstream/master
git push origin master

PR 有冲突怎么办？ ​

bash
# 同步上游 master
git fetch upstream
git checkout master
git merge upstream/master

# 切换到你的功能分支
git checkout feature/your-feature-name

# 变基到最新的 master
git rebase master

# 解决冲突后
git add .
git rebase --continue

# 强制推送（因为历史被重写）
git push origin feature/your-feature-name --force

提交信息写错了怎么办？ ​

bash
# 修改最后一次提交信息
git commit --amend -m "new commit message"

# 强制推送
git push origin feature/your-feature-name --force

如何撤销提交？ ​

bash
# 撤销最后一次提交，保留修改
git reset --soft HEAD~1

# 撤销最后一次提交，丢弃修改
git reset --hard HEAD~1

联系方式 ​

如有任何问题，欢迎通过以下方式联系我们：

相关资源 ​

再次感谢您的贡献！让我们一起打造更好的开源大模型学习社区！ 🚀

基于 Apache-2.0 许可发布

Copyright © 2023-present Datawhale