开源 AI 烹饪书

此仓库包含由社区驱动的实用示例，展示如何使用开源工具和模型构建 AI 应用并解决各种任务。

为烹饪书贡献力量

我们欢迎所有人贡献内容，并珍视每一位贡献者的付出！您可以通过以下几种方式为 开源 AI 烹饪书 做出贡献：

• 通过 GitHub Issues 提交您希望看到的示例或指南的想法。
• 贡献一个新的包含实用示例的笔记本。
• 通过修复问题或拼写错误来改进现有示例。

在贡献之前，请先查看当前的 open issues 和 pull requests，以避免重复他人的工作。

完成贡献后，您可以申请加入 这个组织，以领取徽章。🏅

什么样的 Cookbook 笔记本算优秀？

我们认为，如果 Jupyter 笔记本具备以下特点，Cookbook 将对社区中的每个人最有帮助：

• 实用性: 您的笔记本应提供一个端到端项目或 AI 开发中某个特定方面的示例。目标是面向真实世界的应用场景，但不要过度复杂。清晰地说明目标、挑战以及所涉及的步骤。
• 使用开源工具和模型: 使用遵循宽松许可协议的开源库、数据集和预训练模型。在笔记本中包含所有使用资源的链接。
• 文字清晰: 确保您的文字清晰、简洁，无语法错误。在整个笔记本中保持友好且易于理解的语气。解释您解决问题的步骤、遇到的挑战以及可选的方法。
• 可顺利运行，无错误: 在提交前测试您的笔记本，避免运行时错误。
• 补充现有“菜谱”: 提交前请先浏览现有的笔记本，确认尚未涵盖该主题。我们欢迎多样化的用例、模态、技术和方法！
• 内容中立: 笔记本应保持中立和教育性，不应带有品牌色彩，也不应过多关注特定品牌、产品或开源仓库的推广。

创建拉取请求

要贡献新的示例或指南，请打开一个拉取请求，并标记 @merveenoyan 和 @stevhliu。

以下是一些提示：

• 确保您的笔记本文件名全部使用小写字母。
• 不要忘记将您的笔记本添加到 _toctree.yml 和 index.md 中。
• 在笔记本的第一个标题之后，立即以如下格式添加作者信息：_作者：[Aymeric Roucher](https://huggingface.co/m-ric)_。您可以链接到您的 Hugging Face 个人主页或 GitHub 个人主页。
• 删除无意义的代码单元输出（例如来自 pip install 的输出）。确保笔记本中没有空的代码单元。
• 如果在 Markdown 中使用图片，请将其上传到 huggingface/cookbook-images 数据集。然后在 Markdown 中使用该图片的链接，例如：

![RAG 示意图](https://oss.gittoolsai.com/images/huggingface_cookbook_readme_a9ad0388fbd2.png)

一旦您的拉取请求被合并，该笔记本就会出现在 开源 AI 烹饪书 中。

将 Cookbook 翻译成您的语言

我们非常希望 Cookbook 能够提供更多语言版本！如果您愿意帮助将笔记本翻译成您的语言，请按照以下步骤操作 🙏。

如果部分笔记本已经翻译成您的语言，请将新翻译的笔记本添加到 notebooks/your_language 目录下。别忘了将新翻译的笔记本添加到 notebooks/your_language/_toctree.yml 和 notebooks/your_language/index.md 中。

如果笔记本尚未翻译成您的语言，请在 notebooks 目录下创建一个以您的 LANG-ID 命名的子目录（例如，en 表示英语，zh-CN 表示中文）。LANG-ID 应该是 ISO 639-1 标准的两位小写字母语言代码——可参考 这里。此外，{两小写字母}-{两大写字母} 格式也同样支持，例如 zh-CN。

创建 notebooks/LANG-ID/_toctree.yml 和 notebooks/LANG-ID/index.md，并将翻译后的笔记本添加进去。

最后，在 .github/workflows 文件夹中的 build_documentation.yml 和 build_pr_documentation.yml 文件中，添加您的语言代码（即相同的 LANG-ID）。

Open-Source AI Cookbook 快速上手指南

Open-Source AI Cookbook 是一个由社区驱动的开源项目，汇集了使用开源工具和模型构建 AI 应用及解决各类任务的实用示例（Jupyter Notebook）。本指南将帮助你快速参与贡献或使用其中的资源。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (推荐 WSL2)。
• Python 版本：建议 Python 3.8 或更高版本。
• 前置依赖：
  • Git (用于克隆仓库)
  • Jupyter Lab 或 Jupyter Notebook (用于运行和编辑示例)
  • Hugging Face datasets 和 transformers 库 (大多数示例需要)
• 账号准备：拥有一个 Hugging Face 账号，以便提交 PR 后申请组织徽章。

国内开发者提示：如果访问 Hugging Face 官网或下载模型较慢，建议配置国内镜像源或使用加速服务（如 hf-mirror.com）。

安装步骤

1. 克隆仓库

首先，将 Cookbook 仓库克隆到本地：

git clone https://github.com/huggingface/cookbook.git
cd cookbook

加速方案：如果 GitHub 连接缓慢，可使用国内镜像（如 Gitee 镜像，若有）或配置 Git 代理。

2. 安装依赖

进入项目目录并安装必要的 Python 依赖。虽然每个 Notebook 可能有特定需求，但建议先安装基础环境：

pip install -r requirements.txt

如果根目录没有统一的 requirements.txt，请在运行具体 Notebook 前，根据该文件顶部的说明安装对应库。例如：

pip install transformers datasets accelerate jupyterlab

国内镜像加速：推荐使用清华或阿里镜像源加速安装：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 配置 Hugging Face 镜像 (可选但推荐)

为了在中国大陆地区流畅下载模型和数据集，建议在代码开头或环境变量中设置镜像地址：

export HF_ENDPOINT=https://hf-mirror.com

或在 Python 代码中设置：

import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

基本使用

Cookbook 的核心内容是位于 notebooks/ 目录下的 Jupyter Notebook 文件。你可以直接运行现有的示例学习，或按照规范贡献新的示例。

运行现有示例

假设你要运行一个关于 RAG (检索增强生成) 的英文示例：

1. 启动 Jupyter Lab：

   jupyter lab
   

2. 在浏览器中导航至 notebooks/en/ 目录。
3. 打开任意 .ipynb 文件（例如 rag_llama_index.ipynb）。
4. 按顺序执行单元格即可运行。

贡献新示例 (简要流程)

如果你想贡献一个新的教程：

1. 检查议题：查看 GitHub Issues 确认该主题未被占用。
2. 创建分支：

   git checkout -b my-new-example
   

3. 编写 Notebook：
   • 文件名必须全小写 (如 my_awesome_example.ipynb)。
   • 在第一个标题后立即添加作者信息：_Authored by: [Your Name](Your Profile Link)_。
   • 确保代码无错误且输出清晰（删除 pip install 等无关输出）。
   • 若需图片，请上传至 huggingface/cookbook-images 并在 Markdown 中引用链接。
4. 更新索引：
   • 将新文件添加到对应的 _toctree.yml 和 index.md 中。
5. 提交 PR：

   git add .
   git commit -m "Add new example: my awesome example"
   git push origin my-new-example
   

   在 GitHub 上创建 Pull Request，并标记 @merveenoyan 和 @stevhliu。

中文翻译贡献

如果你想将现有笔记翻译成中文：

1. 在 notebooks/ 下创建语言目录，例如 zh-CN。
2. 复制并翻译对应的 .ipynb 文件到 notebooks/zh-CN/。
3. 创建 notebooks/zh-CN/_toctree.yml 和 notebooks/zh-CN/index.md 并收录新文件。
4. 修改 .github/workflows/build_documentation.yml 和 build_pr_documentation.yml，加入 zh-CN 语言代码以启用构建。