# OpenAI Cookbook

Canonical: https://cqbase.net/zh/entry/openai-cookbook
Chinese: https://cqbase.net/zh/entry/openai-cookbook
English: https://cqbase.net/en/entry/openai-cookbook

> OpenAI 官方的 API 示例和指南，站点在 cookbook.openai.com。

openai/openai-cookbook 用 MIT 许可，收集调用 OpenAI API 的示例和说明，配套站点是 cookbook.openai.com。它适合已经决定用这家 API、想看官方推荐写法的人，而不是泛泛的提示词摘抄。

挑一个和你的调用方式相同的笔记本，对照你使用的模型名和参数。官方示例会随 API 更新，抄下来之前先对一下日期。

## 解决什么问题

[openai/openai-cookbook](https://github.com/openai/openai-cookbook) 是 OpenAI 官方维护的 API 示例与指南集合，配套站点是 [cookbook.openai.com](https://cookbook.openai.com)。它适合已经决定使用这家 API、想看官方推荐写法的人，而不是一份脱离产品的提示词摘抄。仓库用 MIT 许可发布，并未归档。

核验日期为 2026-11-16（Asia/Shanghai）。仓库最近一次推送是 2026-11-14 03:45 UTC，换算为 2026-11-14 11:45（Asia/Shanghai）。根目录 README 很短，真正的目录在网站和仓库的 `registry.yaml` 里。内容主要放在 `examples/`（可运行的笔记本和脚本）和 `articles/`（较长指南）下。2026-11-16 打开站点时，目录里既有较新的 Agents、Codex、Responses、gpt-oss 等内容，也可能仍保留较早的示例；抄任何一篇之前都要看页面日期，并对一下当前 API 文档里的模型名和参数。

## 适合谁

适合已经有 OpenAI 账户和 API 密钥、希望对着官方示例改自己调用方式的开发者。大多数代码示例是 Python，但官方说明其中的思路也可以用到其他语言。密钥可从 [platform.openai.com](https://platform.openai.com/signup) 一类官方入口申请，具体以当时的控制台为准。

若你并不使用 OpenAI API，或只是在寻找可直接粘贴的通用提示词，这个仓库不是最合适的入口。账单、账号和额度问题应走 [OpenAI Help Center](https://help.openai.com/)；Cookbook 的 issue 跟踪器只处理 Cookbook 内容本身的问题，见 [CONTRIBUTING.md](https://github.com/openai/openai-cookbook/blob/main/CONTRIBUTING.md)。

## 怎么用

说明来自 2026-11-16 查阅的仓库 [README](https://github.com/openai/openai-cookbook/blob/main/README.md) 和 [CONTRIBUTING.md](https://github.com/openai/openai-cookbook/blob/main/CONTRIBUTING.md)。日常阅读不必先克隆整个仓库：先在 [cookbook.openai.com](https://cookbook.openai.com) 按主题挑选一篇，站点也提供对应的 Markdown 版本（在页面 URL 后加上 `.md`）。仓库体积很大，只有需要本地跑多篇示例时再克隆。

要运行某一篇时，先设置环境变量，或在项目根目录使用 `.env`（README 写明多数 IDE 会读取其中的 `OPENAI_API_KEY`）：

```bash
export OPENAI_API_KEY="YOUR_API_KEY"
```

不要把密钥写入仓库或对话。CONTRIBUTING 写明：每个示例应列出自己的依赖（例如该目录下的 `requirements.txt`），并在虚拟环境中安装；仓库根目录没有一份适用于全部示例的统一依赖清单。安装完后，从上到下运行该笔记本，并把其中的模型名、接口（例如 Responses 或旧的 Completions 写法）对照当时的 [API 文档](https://developers.openai.com/api/docs)。

若你要改现有示例并准备提交，CONTRIBUTING 还提到可运行：

```bash
python .github/scripts/check_notebooks.py
```

这是给贡献者用的结构检查，不是运行食谱的必要步骤。

## 一个实际例子

下面以「先选一篇与你的调用方式接近的新指南，再在自己的小数据上复现」为路径。本次没有执行任何笔记本，因此不编造 API 返回或费用数字。

1. 打开 [cookbook.openai.com](https://cookbook.openai.com)，按你的实际需求筛选，例如工具调用、结构化输出、Agents 或检索。优先选带有近期日期、并且接口与你正在用的一致的条目，而不是一篇只因为标题眼熟的旧文。
2. 阅读页面上的模型名、前置条件和依赖说明，再对照当前 API 文档。若页面仍写着你账户里已经不可用的型号，先改成文档里的当前名称，不要原样运行。
3. 在单独的虚拟环境中安装该示例列出的依赖，设置 `OPENAI_API_KEY`，用你自己的一小段输入替换示例数据，然后运行。预期效果：调用能够完成，并展示该食谱要说明的步骤（例如一次工具调用或一次结构化输出）。请自己检查结果。
4. 确认密钥和任何第三方凭证都没有被写入笔记本。若示例还依赖外部服务，先读清费用和权限，再决定要不要继续。

## 常见坑

- 把根目录 README 当成完整目录。它几乎只指向网站；完整索引是网站和 `registry.yaml`。
- 不看日期就复制旧笔记本。站点上新旧条目并存，模型名和接口都可能已经变化。
- 假设存在一份根目录 `requirements.txt` 能跑通所有示例。CONTRIBUTING 要求按你改动或运行的那一篇安装依赖。
- 把密钥写进笔记本或提交 `.env`。官方要求从环境变量读取。
- 在 Cookbook 的 GitHub issue 里询问账单或账号问题。官方把这类问题指向 Help Center。
- 为了读一篇短文就克隆整个巨型仓库。先用网站，需要本地运行时再克隆，或只下载单篇文件。

## FAQ

### 不克隆仓库能开始看吗？

可以。官方README 把 [cookbook.openai.com](https://cookbook.openai.com) 当作主要入口。只有需要本地运行或对照源文件时，才需要克隆或下载对应路径。

### 怎么配置 API 密钥？

README 要求设置环境变量 `OPENAI_API_KEY`，或在仓库根目录使用包含该变量的 `.env`。不要把密钥写进代码或提交到 git。密钥本身从 OpenAI 官方控制台获取。

### 示例一定是最新的吗？

不一定。仓库仍在更新，但目录里会同时留下较早的文章。运行前请看该条目的日期，并核对该页使用的模型名和 API 是否仍出现在当前官方文档中。

### 完整目录在哪里？

公开浏览用 [cookbook.openai.com](https://cookbook.openai.com)。仓库里与网站对应的索引是 [registry.yaml](https://github.com/openai/openai-cookbook/blob/main/registry.yaml)。新内容按 CONTRIBUTING 应放进 `examples/<topic>/` 或 `articles/`。

### 许可证是什么？

仓库声明为 MIT License，见 [LICENSE](https://github.com/openai/openai-cookbook/blob/main/LICENSE)。商用或再分发前请自行阅读许可全文。运行示例所产生的 API 费用，以你账户的官方计费为准，本文不编造价格。

## 来源与许可

仓库 [openai/openai-cookbook](https://github.com/openai/openai-cookbook) 使用 MIT 许可。本文依据 2026-11-16 查阅的 README、[CONTRIBUTING.md](https://github.com/openai/openai-cookbook/blob/main/CONTRIBUTING.md)、[cookbook.openai.com](https://cookbook.openai.com) 以及仓库中的 `registry.yaml` 结构，用自己的话写成，供 CQBase 上下文库使用。若目录、依赖或 API 写法有变，以网站和官方 API 文档为准。

## 收录信息

- 作者: openai
- 许可证: MIT
- 来源: https://github.com/openai/openai-cookbook
- 收录: 2026-11-15
- GitHub 星标: 77132（采集 2026-11-15）

