python-openai-demos: OpenAI API 全功能入门指南

从一道"猫咪打油诗"说起

打开 python-openai-demos 仓库，第一个运行的脚本是 chat.py。它的任务很简单：让 AI 写一首关于饥饿猫咪的日式俳句（haiku）。系统提示词被设定为"一个喜欢引用猫咪并大量使用表情符号的助手"，于是你得到了一首带着猫粮emoji的俳句——这就是这个仓库最朴素的目标：让任何人都能在几分钟内跑通 OpenAI API 的核心能力。

这个仓库由 Pamela Fox 创建维护。Pamela 是微软的知名技术布道师，曾在 Google 和 Khan Academy 任职，长期活跃于 Python 和教育技术社区。她以"让复杂技术变得平易近人"著称，python-openai-demos 正是这种理念的体现——不是抛出一个庞大的框架，而是用 30+ 个独立脚本，逐层递进地展示 OpenAI SDK 的每一个功能点。

为什么需要这个项目

OpenAI API 的能力远比"问答"丰富。Function Calling 让模型调用外部工具，Structured Outputs 让输出直接映射到代码对象，RAG 让模型"阅读"私有文档。但官方文档分散、示例零碎、缺少渐进路径。python-openai-demos 的价值在于：它是一条从简单到复杂的自学路径，每个脚本只做一件事，注释清晰，可以单独运行、修改、组合。

如果你刚接触 OpenAI API，这个仓库是比官方 Quickstart 更好的起跑点——它覆盖了官方示例没有涉及的 Function Calling 全链路、Structured Outputs 嵌套模型，以及 RAG 混合检索等进阶主题。

核心功能模块拆解

模块一：Chat Completions（对话补全）

基础到进阶层层递进，共 8 个脚本：

脚本	演示内容
`chat.py`	一次性对话，最简 API 调用
`chat_stream.py`	流式响应，用 `stream=True` 实现打字机效果
`chat_history.py`	多轮对话，`input()` 循环维护历史消息
`chat_history_stream.py`	流式 + 多轮结合
`chat_safety.py`	Azure AI Content Safety 异常处理
`chat_async.py`	`asyncio.gather` 并发发送多条请求
`chained_calls.py`	多步骤链式调用：生成 → 审查 → 修订
`few_shot_examples.py`	小样本提示（Few-shot Prompting）

特别值得关注的是 chained_calls.py，它演示了如何用多次 API 调用实现"AI 编辑工作流"：第一次生成解释文字，第二次让 AI 扮演编辑角色提供反馈，第三次根据反馈修订。这种模式是构建复杂 AI 应用的基础原子操作。

模块二：Function Calling（函数调用）

这是 OpenAI API 最强大的特性之一，仓库中用 4 个脚本完整展示了从"声明"到"执行"到"多工具协作"的全链路：

function_calling_basic.py    → 声明工具，打印模型返回的调用请求（无执行）
function_calling_call.py    → 解析参数，执行本地 Python 函数
function_calling_extended.py → 完整闭环：执行后将结果传回模型，获得最终答案
function_calling_multiple.py → 暴露 lookup_weather + lookup_movies 多个工具

核心原理是：模型在 message.tool_calls 中返回 {name, arguments} 结构，其中 arguments 是符合 JSON Schema 的参数字符串。开发者负责解析参数、执行本地逻辑、（可选）将结果以 tool 角色消息发回模型。代码示例：

if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    # 解析 arguments 并执行本地函数
    args = json.loads(tool_call.function.arguments)
    result = lookup_weather(**args)

模块三：Structured Outputs（结构化输出）

结合 Pydantic 数据模型，强制模型输出符合预定义 schema 的 JSON。这解决了"模型输出不稳定"这个 AI 应用开发中的核心痛点：

from pydantic import BaseModel

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model=MODEL_NAME,
    messages=[...],
    response_format=CalendarEvent,  # 强制输出 CalendarEvent 结构
)
event = completion.choices[0].message.parsed  # 直接得到 CalendarEvent 对象

仓库还演示了 Pydantic 的高级用法：字段描述（引导模型理解意图）、枚举类型（限制可选值）、嵌套模型（处理复杂结构）、与 Function Calling 结合。

模块四：RAG（检索增强生成）

RAG 是当前最主流的 LLM 应用架构，项目用 6 个脚本从简单到复杂展示了全流程：

脚本	RAG 阶段
`rag_csv.py`	基础检索：从 CSV 匹配答案
`rag_multiturn.py`	多轮对话中的上下文维护
`rag_queryrewrite.py`	查询重写，改善检索质量
`rag_documents_ingestion.py`	PDF 文档摄取：PyMuPDF → Markdown → LangChain 分块 → OpenAI Embedding → JSON 存储
`rag_documents_flow.py`	从本地 JSON 检索匹配的文档块
`rag_documents_hybrid.py`	混合检索：向量检索 + 关键词检索（lunr）+ Reciprocal Rank Fusion 合并 + CrossEncoder 重排

rag_documents_hybrid.py 尤其值得关注，它实现了一个生产级的混合检索 pipeline：先分别用 sentence-transformers 做向量相似度搜索、用 lunr 做全文关键词搜索，然后用 RRF（Reciprocal Rank Fusion）合并两种排序结果，最后用 CrossEncoder 交叉编码器做语义重排。这是当前 RAG 系统的主流最佳实践。

模块五：Reasoning Models（推理模型）

reasoning.py 展示了 OpenAI 最新推理模型的使用方式。通过 reasoning_effort 参数控制推理强度，模型返回的 reasoning 字段包含思维链过程：

response = client.chat.completions.create(
    model=MODEL_NAME,  # 需要 gpt-5 或支持推理的模型
    messages=[{"role": "user", "content": "How many r's are in strawberry?"}],
    reasoning_effort="low",
)
# 访问推理过程
if hasattr(response.choices[0].message, "reasoning"):
    print(response.choices[0].message.reasoning)

架构设计特点

每个脚本原子化、独立化。这是项目最显著的设计哲学——没有抽象框架，没有继承体系，每个脚本都是一个最小可用单元。开发者可以：

单独复制某个脚本到自己的项目
直接运行 python chat.py 验证效果
逐个功能探索，无需理解前置知识

多后端统一接入层。所有脚本都通过统一的 API_HOST 环境变量，支持四个后端：

OpenAI.com：标准商业 API，需 OPENAI_KEY
Azure OpenAI：企业级部署，使用 azure-identity 的 DefaultAzureCredential 自动获取 Token
GitHub Models：在 GitHub Codespaces 中免费使用，无需额外配置
Ollama：本地部署，数据完全私有

这种设计让学习者可以在不同阶段选择不同后端：初学者用 GitHub Models 零成本起步，企业用户走 Azure，生产部署自建 Ollama。

代码质量评估

项目使用 ruff + black 统一代码风格（行长 120，Python 3.11+），.devcontainer/ 支持 VS Code Remote Container 一键构建开发环境，CONTRIBUTING.md 遵循微软开源规范，GitHub Actions CI 自动化测试。整体代码质量评分 85/100——逻辑清晰、文档详尽，但作为教学脚本集合，缺少生产级的错误处理和日志体系。

局限与注意事项

无 Web UI：纯 CLI 脚本，不适合非技术用户直接使用
需要有效 API Key：本地运行需要申请 OpenAI/Azure/等账号，有使用成本
RAG 检索依赖 Embedding 质量：rag_documents_hybrid.py 中的 CrossEncoder 重排依赖专用模型，需额外安装
不支持流式 + Function Calling 组合：目前 API 限制，流式模式下无法同时使用工具调用

行业意义

python-openai-demos 代表了 AI 应用开发的教育趋势：从"学框架"转向"学 API 本身"。随着 LLM API 能力越来越强、工具越来越标准化，深入理解 API 原语（Chat Completions、Function Calling、Structured Outputs）比掌握某个特定框架更重要。这个仓库正是这个理念的最佳实践——它让开发者掌握底层能力，而不是被 LangChain/LlamaIndex 等框架抽象掉细节。

适用人群：刚接触 OpenAI API 的 Python 开发者、想构建 AI 应用的产品工程师、需要教学示例的技术布道师。

python-openai-demos: OpenAI API 全功能入门指南

从一道"猫咪打油诗"说起

为什么需要这个项目

如果你刚接触 OpenAI API，这个仓库是比官方 Quickstart 更好的起跑点——它覆盖了官方示例没有涉及的 Function Calling 全链路、Structured Outputs 嵌套模型，以及 RAG 混合检索等进阶主题。

核心功能模块拆解

模块一：Chat Completions（对话补全）

基础到进阶层层递进，共 8 个脚本：

脚本	演示内容
`chat.py`	一次性对话，最简 API 调用
`chat_stream.py`	流式响应，用 `stream=True` 实现打字机效果
`chat_history.py`	多轮对话，`input()` 循环维护历史消息
`chat_history_stream.py`	流式 + 多轮结合
`chat_safety.py`	Azure AI Content Safety 异常处理
`chat_async.py`	`asyncio.gather` 并发发送多条请求
`chained_calls.py`	多步骤链式调用：生成 → 审查 → 修订
`few_shot_examples.py`	小样本提示（Few-shot Prompting）

模块二：Function Calling（函数调用）

这是 OpenAI API 最强大的特性之一，仓库中用 4 个脚本完整展示了从"声明"到"执行"到"多工具协作"的全链路：

function_calling_basic.py    → 声明工具，打印模型返回的调用请求（无执行）
function_calling_call.py    → 解析参数，执行本地 Python 函数
function_calling_extended.py → 完整闭环：执行后将结果传回模型，获得最终答案
function_calling_multiple.py → 暴露 lookup_weather + lookup_movies 多个工具

if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    # 解析 arguments 并执行本地函数
    args = json.loads(tool_call.function.arguments)
    result = lookup_weather(**args)

模块三：Structured Outputs（结构化输出）

结合 Pydantic 数据模型，强制模型输出符合预定义 schema 的 JSON。这解决了"模型输出不稳定"这个 AI 应用开发中的核心痛点：

from pydantic import BaseModel

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model=MODEL_NAME,
    messages=[...],
    response_format=CalendarEvent,  # 强制输出 CalendarEvent 结构
)
event = completion.choices[0].message.parsed  # 直接得到 CalendarEvent 对象

仓库还演示了 Pydantic 的高级用法：字段描述（引导模型理解意图）、枚举类型（限制可选值）、嵌套模型（处理复杂结构）、与 Function Calling 结合。

模块四：RAG（检索增强生成）

RAG 是当前最主流的 LLM 应用架构，项目用 6 个脚本从简单到复杂展示了全流程：

脚本	RAG 阶段
`rag_csv.py`	基础检索：从 CSV 匹配答案
`rag_multiturn.py`	多轮对话中的上下文维护
`rag_queryrewrite.py`	查询重写，改善检索质量
`rag_documents_ingestion.py`	PDF 文档摄取：PyMuPDF → Markdown → LangChain 分块 → OpenAI Embedding → JSON 存储
`rag_documents_flow.py`	从本地 JSON 检索匹配的文档块
`rag_documents_hybrid.py`	混合检索：向量检索 + 关键词检索（lunr）+ Reciprocal Rank Fusion 合并 + CrossEncoder 重排

模块五：Reasoning Models（推理模型）

reasoning.py 展示了 OpenAI 最新推理模型的使用方式。通过 reasoning_effort 参数控制推理强度，模型返回的 reasoning 字段包含思维链过程：

response = client.chat.completions.create(
    model=MODEL_NAME,  # 需要 gpt-5 或支持推理的模型
    messages=[{"role": "user", "content": "How many r's are in strawberry?"}],
    reasoning_effort="low",
)
# 访问推理过程
if hasattr(response.choices[0].message, "reasoning"):
    print(response.choices[0].message.reasoning)

架构设计特点

每个脚本原子化、独立化。这是项目最显著的设计哲学——没有抽象框架，没有继承体系，每个脚本都是一个最小可用单元。开发者可以：

单独复制某个脚本到自己的项目
直接运行 python chat.py 验证效果
逐个功能探索，无需理解前置知识

多后端统一接入层。所有脚本都通过统一的 API_HOST 环境变量，支持四个后端：

OpenAI.com：标准商业 API，需 OPENAI_KEY
Azure OpenAI：企业级部署，使用 azure-identity 的 DefaultAzureCredential 自动获取 Token
GitHub Models：在 GitHub Codespaces 中免费使用，无需额外配置
Ollama：本地部署，数据完全私有

这种设计让学习者可以在不同阶段选择不同后端：初学者用 GitHub Models 零成本起步，企业用户走 Azure，生产部署自建 Ollama。

代码质量评估

局限与注意事项

无 Web UI：纯 CLI 脚本，不适合非技术用户直接使用
需要有效 API Key：本地运行需要申请 OpenAI/Azure/等账号，有使用成本
RAG 检索依赖 Embedding 质量：rag_documents_hybrid.py 中的 CrossEncoder 重排依赖专用模型，需额外安装
不支持流式 + Function Calling 组合：目前 API 限制，流式模式下无法同时使用工具调用

行业意义

适用人群：刚接触 OpenAI API 的 Python 开发者、想构建 AI 应用的产品工程师、需要教学示例的技术布道师。