generative-ai-for-beginners 增强功能路线图：从安全修复到代码质量体系的落地实践

本文以 translations/bg/docs/ENHANCED_FEATURES_ROADMAP.md（英文原版位于 ENHANCED_FEATURES_ROADMAP.md）为核心，解析 generative-ai-for-beginners 这门 21 课生成式 AI 课程在"安全加固、代码质量、教育扩展、API 现代化"四个维度上的演进路线。结合仓库中真实落地的配置文件与源码（pyproject.toml、.eslintrc.json、.prettierrc、shared/python、tests/），你可以理解每一项"路线图建议"背后具体落成了什么样的工程设施，以及哪些仍属于待办规划。

路线图全景：四个方向、四个阶段

该文档将课程代码库按"安全性、代码质量、教育效果"三条标准做了系统性审查，并把改进项组织为两大结构：

• 按领域划分：安全（优先级：关键）、代码质量、教育扩展、API 现代化、基础设施、开发体验、多语言/多技术栈支持、性能优化、可访问性；
• 按时间划分：阶段 1（第 1–2 周）处理关键安全修复与质量基建，阶段 2（第 3–4 周）推进 API 现代化与 CI/CD，阶段 3（第 2–3 月）扩展课程与开发环境，阶段 4（第 4 月起）补全测试体系与认证项目。

对照仓库当前状态，阶段 1 的四项任务在文档中已标记为完成（勾选），且都能在当前仓库中找到实物证据：安全修复已提交、pyproject.toml 与 Lint 配置已存在、shared/python/ 共享模块已创建、SECURITY.md 已就位。下文逐项展开。

安全加固：五项关键问题的修复清单

文档第 1.1 节列出了被判定为"关键优先级"的五项安全问题及其修复状态。这些修复覆盖了密钥管理、环境校验、函数调用安全、资源泄漏与请求超时五个典型薄弱面：

问题	受影响文件	状态
硬编码 SECRET_KEY	05-advanced-prompts/python/aoai-solution.py	已修复
缺少环境变量校验	多个 JS/TS 文件	已修复
不安全的函数调用	11-integrating-with-function-calling/js-githubmodels/app.js	已修复
文件句柄泄漏	08-building-search-applications/scripts/	已修复
缺少请求超时	09-building-image-applications/python/	已修复

可以从源码中逐项验证这些"已修复"声明：

1. 硬编码 SECRET_KEY → 运行时随机生成。 在 aoai-solution.py 中，Flask 应用现在这样初始化密钥：

app.config['SECRET_KEY'] = os.environ.get('FLASK_SECRET_KEY', os.urandom(32))

优先从 FLASK_SECRET_KEY 环境变量读取，缺省时用 os.urandom(32) 生成 32 字节随机数，彻底消除了密钥入库的风险。

2. 文件句柄泄漏 → 上下文管理器。 以 transcript_enrich_lite.py 为例，输入输出文件均采用 with open(...) as f: 模式读写，保证句柄确定性地关闭；图片示例 aoai-app.py 中 with open(image_path, "wb") as image_file: 同样是这一模式的体现。

3. 请求超时与重试 → 共享安全请求封装。 路线图第 1.2 节建议"增加 API 调用限频与指数退避示例"，仓库给出的答案是一个可直接复用的封装 api_utils.py：

def make_safe_request(url, method="GET", timeout: int = 30, retries: int = 3, **kwargs):
    # 每次请求强制携带 timeout，失败后重试，重试耗尽抛出 RequestException
    for attempt in range(retries):
        try:
            response = requests.request(method=method, url=url, timeout=timeout, **kwargs)
            response.raise_for_status()
            return response
        except RequestException as e:
            ...

默认 30 秒超时、3 次重试，并在源码注释中预留了"指数退避"扩展点。这个函数正是"缺少请求超时"一类问题的通用解法，配合 test_api_utils.py 中的 test_retries_then_raises 测试（断言重试恰好 3 次后才抛异常），行为边界清晰可验证。

除上述修复外，文档还在第 1.2 节规划了三类进阶安全能力，属于尚未落地的建议：API 调用限频示例、API 密钥轮换（结合 Azure Key Vault 等托管方案）的内容安全集成（输入/输出双向内容审核）。这些方向与课程 13-securing-ai-applications 一课的主题直接衔接。

代码质量体系：三份配置文件 + 一个共享模块

Lint 与格式化配置已实际落地

文档第 2.1 节声明新增了三个配置文件，当前仓库中均已存在，且内容比"配置存在"更进一步：

• .eslintrc.json：基于 eslint:recommended，并针对教学代码做了针对性取舍——eqeqeq: error（强制严格相等）、no-eval: error、no-new-func: error、no-script-url: error 等规则直接拦截危险写法；no-unused-vars 与 no-console 降级为警告或关闭，避免课程示例代码产生过多噪音。对 TypeScript 文件通过 overrides 启用 @typescript-eslint/recommended，并对 explicit-function-return-type、no-explicit-any 等给出 warn 级约束。
• .prettierrc：统一 printWidth: 100、单引号、semi: true、arrowParens: always、endOfLine: lf，与 ESLint 的 100 列约定保持一致。
• pyproject.toml：是整个 Python 侧质量体系的"总控台"，详见下文。

pyproject.toml：从依赖声明到工具链的一体化配置

pyproject.toml 将课程项目声明为一个正式可安装的 Python 包（requires-python = ">=3.10"），并把路线图提到的 Black、Ruff、mypy、pytest 全部纳入：

dependencies = [
    "openai>=1.0.0",
    "python-dotenv>=1.0.0",
    "requests>=2.31.0",
    "azure-ai-inference>=1.0.0b1",
    "tiktoken>=0.5.0",
]

[project.optional-dependencies]
dev = ["black>=24.0.0", "isort>=5.13.0", "mypy>=1.8.0",
       "ruff>=0.2.0", "pytest>=8.0.0", "pytest-cov>=4.1.0"]

注意 tiktoken 已被列为正式依赖——这正是文档第 8.1 节"token 优化：tiktoken 示例"的落地伏笔，学生可以直接在课程代码中做分词计数与提示词压缩实验。

各工具配置段的实际取值：

• [tool.black]：line-length = 100，目标 py310–py312，排除 node_modules、.venv 等目录；
• [tool.ruff]：line-length = 100、target-version = "py310"，lint 规则集为 E/W/F/I/B/C4/UP/S——其中 S（flake8-bandit）是安全规则组，意味着"安全"这一主题不只是文档口号，而是写进了静态检查；同时豁免 S101（教学代码中允许 assert）；
• [tool.mypy]：python_version = "3.10"、warn_return_any = true、check_untyped_defs = true，但 disallow_untyped_defs = false——这是一个面向课程场景的渐进式策略：先强制"已有类型标注的定义必须检查正确"，而不强制所有函数补齐标注，正好对应第 2.3 节"为所有 Python 文件补充 type hints"这条阶段 2 待办；
• [tool.pytest.ini_options]：testpaths = ["tests"]、addopts = "-v --tb=short"。

shared/python 共享工具模块：三个文件的职责与实现

文档第 2.2 节预告的 shared/python/ 模块如今包含三个文件，每个都带有完整的 docstring 与可运行的 doctest 示例：

1. env_utils.py —— 环境变量安全读取

• get_required_env(var_name, description=None)：变量缺失或为空时抛出带指引信息的 ValueError（提示"请在 .env 文件或环境中设置"），description 参数会进入报错信息，方便学生定位是哪个配置项缺失；
• validate_env_vars(*var_names)：批量校验多个变量，一次报告全部缺失项（Missing required environment variables: VAR_X, VAR_Y），而非只报第一个——测试 test_env_utils.py 专门验证了"报告所有缺失变量"的行为；
• get_env_with_default(var_name, default)：带默认值的宽松读取，docstring 示例即 get_env_with_default("MODEL_NAME", "gpt-4o")。

2. input_validation.py —— 防提示注入的输入净化

这是与生成式 AI 应用安全关系最密切的文件，提供四层防护：

• validate_number_input(value, min_val=1, max_val=100)：带区间的整数校验，异常信息包含字段名；
• validate_text_input(value, max_length=500, min_length=1, allow_empty=False)：长度与空值约束；
• sanitize_prompt_input(value, max_length=1000, strict=False)：核心函数。它先剔除空字节与控制字符，再按正则删除四类注入模式——模板注入 {{...}}、变量替换 ${...}、<script> 标签、javascript: URL；strict=True 时仅保留字母数字、空格与基础标点；最后归一化空白并做长度断言；
• validate_email / validate_url(require_https=True)：格式校验，URL 默认只放行 HTTPS。

这些函数把 13-securing-ai-applications 一课讲授的"提示注入防护"概念变成了可复制的代码原语。

3. api_utils.py —— 安全 API 封装

除前文提到的 make_safe_request 外，还有三个工厂/工具函数：

• create_openai_client(api_key=None)：未显式传 key 时读取 OPENAI_API_KEY，缺失即抛 ValueError，避免空 key 静默透传到 SDK；
• create_azure_openai_client(endpoint=None, api_key=None)：读取 AZURE_OPENAI_ENDPOINT 与 AZURE_OPENAI_API_KEY，并将 base_url 组装为 f"{endpoint}/openai/v1/"——注释中说明该 v1 端点驱动 Responses API，因此不需要 api_version 参数，这正是第 4 节"API 现代化"（去掉 api_version 式旧用法）的具体体现；
• download_image(url, save_path, timeout=30)：复用 make_safe_request 下载图像并自动创建目标目录，直接服务于 09-building-image-applications 一类课程脚本。

tests/test_api_utils.py 用 monkeypatch 模拟缺 key、缺 endpoint 场景，确认两种客户端的失败路径都抛出可读的 ValueError 而不是晦涩的 SDK 异常。

测试框架：pytest 配置与测试骨架

文档第 2.3 节建议"添加 pytest 配置与示例测试、Jest 配置"。仓库当前已落地 pytest 一侧：

• 配置见 pyproject.toml 的 [tool.pytest.ini_options]；
• 测试位于 tests/ 目录：test_env_utils.py、test_api_utils.py、test_input_validation.py，共覆盖 3 个共享模块的正常路径、边界路径与异常路径（如"空字符串也算缺失"、"重试 3 次后抛错"）；
• 测试风格全部使用 pytest 的 monkeypatch fixture 操控环境变量，不污染真实环境，这一写法本身也是给学生的示范。

Jest 一侧的配置文件尚未在仓库中出现，属于文档中的规划项。

API 现代化：从旧式调用到新客户端模型

文档第 4.1 节给出了一张弃用 API 对照表，指出课程脚本需要迁移的三类旧模式：

旧模型	新模型	受影响文件
openai.api_type = "azure"	AzureOpenAI() 客户端	08-building-search-applications/ 中多个脚本
openai.ChatCompletion.create()	client.chat.completions.create()	多个 notebook
df.append()（pandas）	pd.concat()	RAG notebook

第 4.2 节则列出了值得在课程中新增演示的 API 能力：结构化输出（JSON mode、严格 schema 函数调用）、视觉能力（图像分析、多模态提示）、Assistants API（代码解释器、文件搜索、自定义工具）。

仓库侧与之相互印证的事实是：shared/python/api_utils.py 中两个客户端工厂统一返回新版 OpenAI 客户端对象，Azure 侧通过 v1 端点免去 api_version；.env.copy 模板中 AZURE_OPENAI_API_VERSION='2024-10-21' 仍保留为注释默认值，供仍需旧版 REST 风格的脚本使用。也就是说，"新客户端模型"已经是共享库的默认姿势，而旧式散落脚本（如 08 课脚本、RAG notebook）的逐文件迁移是阶段 2 的未完成事项。

基础设施与开发体验：路线图建议 vs 仓库现状

CI/CD 工作流（规划中）

文档第 5 节给出了两个完整的工作流定义，作为推荐配置：code-quality.yml（python-lint 作业：setup-python@v5 + 3.10 + ruff check . && black --check .；js-lint 作业：Node 20 + npm ci + npx eslint .）与 security.yml（CodeQL 分析 javascript/python + dependency-review-action@v4）。这两份 yaml 本身尚未进入 [.github/workflows] 目录，但其中每一条命令与 pyproject.toml 的工具配置是严格对齐的（ruff/black 的行宽、规则集），落地时可直接复用。

DevContainer（已存在，细节略有差异）

文档第 6.1 节推荐的 DevContainer 以 mcr.microsoft.com/devcontainers/universal:2 为基底，安装 Python 3.11 与 Node 20 特性，预装 Python/Pylance/Jupyter/Ruff 类扩展（推荐文本为 charliermarsh.ruff 与 black 格式化器）、ESLint 与 Prettier 扩展，并设置 editor.formatOnSave: true 与 postCreateCommand。

当前仓库的 .devcontainer/devcontainer.json 实际采用 universal:2.13 镜像、要求 4 CPU、updateContentCommand 安装 requirements.txt、postCreateCommand 执行 bash .devcontainer/post-create.sh，VSCode 扩展清单与推荐列表基本一致（ms-python.python、ms-python.vscode-pylance、ms-toolsai.jupyter、ms-python.black-formatter、charliermarsh.ruff、dbaeumer.vscode-eslint、esbenp.prettier-vscode、github.copilot），并按文件类型分别指定了 Black（Python）与 Prettier（JS/TS）作为默认格式化器。可以推断：路线图推荐配置与现行配置在意图上完全一致，差异仅在镜像版本与初始化脚本细节上。

环境变量模板与配置基线

.env.copy 模板体现了"缺少环境变量校验"修复后的配置基线，涵盖四组凭据：

• OpenAI：OPENAI_API_KEY；
• Azure OpenAI（Microsoft Foundry）：AZURE_OPENAI_API_VERSION、AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_DEPLOYMENT、AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT；
• Microsoft Foundry Models（多供应商模型目录）：AZURE_INFERENCE_ENDPOINT、AZURE_INFERENCE_CREDENTIAL；
• Hugging Face：HUGGING_FACE_API_KEY。

这些变量名与 shared/python/api_utils.py 的读取逻辑、env_utils.validate_env_vars 的批量校验形成闭环：模板定义"需要哪些变量"，工具模块负责"缺失时给出明确报错"。

教育扩展与多技术栈覆盖（规划项）

文档第 3 与第 7 节描述了课程内容层面的扩展规划，这些在当前仓库中大部分尚未实现：

• 新课程：第 22 课"AI 应用安全"（提示注入攻防、密钥管理、内容审核、限频）、第 23 课"生产部署"（容器化、CI/CD、监控、成本控制）、第 24 课"进阶 RAG"（混合检索、重排策略、多模态 RAG、评估指标）；
• 既有课程增强：06 课加流式响应示例、07 课加会话记忆模型、08 课加向量数据库对比、09 课加图像编辑/变体、11 课加并行函数调用、15 课加分块策略对比、17 课加多智能体编排；
• 技术栈覆盖现状表：Python 全覆盖；TypeScript 覆盖 06–09 与 11 课；JavaScript 覆盖 06–08 与 11 课；.NET/C# 部分覆盖（各课程目录下的 dotnet/ notebook）。对照仓库目录可确认这一判断：06-text-generation-apps、07-building-chat-applications、11-integrating-with-function-calling 等目录下确实同时存在 python/、js-githubmodels/、typescript/ 子目录；
• 建议新增语言：Go（AI/ML 工具链增长）、Rust（性能关键场景）、Java/Kotlin（企业应用）。

性能与成本优化建议

文档第 8 节提出三条代码级优化路径与一组成本示例方向：

1. Async/Await：批量处理的异步示例、并发 API 调用演示；
2. 缓存策略：embedding 缓存、响应缓存模型；
3. token 优化：结合 tiktoken 做分词统计与提示词压缩——注意 tiktoken>=0.5.0 已在 pyproject.toml 中成为正式依赖，是三条建议中最接近落地的一条；
4. 成本示例：按任务复杂度选模型、面向 token 效率设计提示词、批量接口处理大规模任务。

执行优先级与当前进度

文档第 10 节的四阶段清单可作为跟踪本项目工程化进度的总台账：

阶段	时间窗	任务	仓库现状
阶段 1	第 1–2 周	关键安全修复、质量配置、共享工具、安全指引	全部完成（文档已勾选，仓库可见 shared/python、pyproject.toml、SECURITY.md 等实物）
阶段 2	第 3–4 周	迁移弃用 API、补全 type hints、CI/CD 质量工作流、安全扫描工作流	未完成，属于下一步重点
阶段 3	第 2–3 月	安全新课、生产部署课、DevContainer 增强、交互演示	部分完成（DevContainer 已存在）
阶段 4	第 4 月起	进阶 RAG 课、语言覆盖扩展、完整测试体系、认证项目	规划中

结论：这份路线图不是泛泛的愿景清单，而是一份与仓库实物一一对应的工程台账。阶段 1 的"安全 + 质量基建"已经在当前代码库中兑现为可执行、可测试的具体产物——从 aoai-solution.py 的密钥修复，到 shared/python 的三层防御工具，再到 tests/ 的行为验证，构成了"教学课程代码同样应当具备生产级安全与质量基线"的完整示范；阶段 2 起的 API 迁移、CI/CD 与安全扫描工作流则是当前最值得关注的后续演进方向。