Generative AI for Beginners 课程质量增强路线图全解析安全加固、代码质量与 API 现代化的落地实践【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本文基于仓库中《强化機能および改善ロードマップ》enhanced-features-roadmap 日文版英文原版见 docs/ENHANCED_FEATURES_ROADMAP.md整理成文。该路线图基于对课程代码库的全面审查与行业最佳实践分析从安全性、代码质量、教育有效性三个维度提出即刻修复、短期改进与长期扩展建议。读完本文你将掌握该 21 课生成式 AI 课程在密钥管理、输入校验、API 客户端封装、CI/CD 与 DevContainer 等方向的具体落地方式并了解每项改进在仓库中的真实实现位置。路线图背景一份可执行的课程质量提升清单Generative AI for Beginners 是一个覆盖 21 课时的生成式 AI 入门课程Python / TypeScript / JavaScript / .NET 多语言示例随着课程迭代维护者对代码库进行了全面的安全、代码质量与教育有效性审查并产出了这份分层级Critical 优先级 → 阶段式实施的改进路线图。它并非空泛的愿景文档而是大多数条目已经在仓库中落地的实现记录包括已完成的紧急安全修复、新增的共享工具模块、测试套件、CI/CD 工作流与 DevContainer 配置以及仍待推进的新课主题与性能优化方向。文章将按路线图原始结构共 10 大板块逐层展开并在每个板块中结合仓库源码与测试文件给出可验证的实现细节方便读者对照原文进行二次开发或评估。1. 安全增强优先级Critical1.1 已完成的紧急修复路线图首先列出一批在审查中被发现的高危问题并在随后的迭代中全部修复问题影响文件状态硬编码的 SECRET_KEY05-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/已修复这些修复对应的安全最佳实践被沉淀为独立的 docs/SECURITY_GUIDELINES.md安全指南。该指南覆盖环境变量管理、输入校验与清洗、API 安全、提示词注入防护、HTTP 请求安全、错误处理、文件操作与代码质量工具八大主题例如环境变量推荐getenv 显式校验禁止直接os.environ[KEY]缺失时抛KeyError严禁硬编码密钥提示词注入用户输入直接拼接进 prompt 是危险的应先行清洗如删除{{...}}模板注入与${...}变量替换模式再放入结构化messagesHTTP 请求所有请求必须设置超时如timeout30并调用raise_for_status()文件操作使用上下文管理器关闭句柄并通过Path.resolve()校验目标路径防止路径穿越Path Traversal。1.2 建议追加的安全特性待办方向路线图同时提出三项尚未在课程中普遍展开的安全功能示例作为后续改进方向限流Rate Limiting示例为 API 调用增加限流实现并演示指数退避exponential backoff模式API 密钥轮换文档化密钥轮换最佳实践并引入 Azure Key Vault 之类的托管方案内容安全集成接入 Azure Content Safety API演示对输入/输出的内容审核moderation模式。值得注意的是仓库中的 shared/python/api_utils.py 已经为指数退避预留了实现位置——make_safe_request在每次重试前有注释# Exponential backoff could be added here说明这是一条已被识别的、可继续扩展的代码路径。2. 代码质量改进2.1 已新增的配置文件文件目的.eslintrc.jsonJavaScript/TypeScript 的 lint 规则.prettierrc代码格式化规范pyproject.tomlPython 工具链配置Black、Ruff、mypy以 pyproject.toml 为例它集中声明了完整的 Python 工程化配置项目元数据requires-python 3.10依赖包括openai1.0.0、python-dotenv1.0.0、requests2.31.0、azure-ai-inference1.0.0b1、tiktoken0.5.0开发依赖[project.optional-dependencies].devblack、isort、mypy、ruff、pytest、pytest-cov[tool.black]行宽 100目标 Python 3.10–3.12并排除了.git、node_modules、build、dist等目录[tool.ruff.lint]启用E/Wpycodestyle、FPyflakes、Iisort、Bflake8-bugbear、C4comprehensions、UPpyupgrade、Sflake8-bandit 安全类规则并针对教学代码豁免E501行长与S101断言使用[tool.pytest.ini_options]testpaths [tests]识别test_*.py/*_test.py默认以-v --tbshort运行。2.2 共享工具模块shared/python/路线图规划并落地了全新的shared/python/模块包含三个文件每个文件都带完整的 docstring 与类型标注是课程代码质量的标杆env_utils.pyshared/python/env_utils.py环境变量安全处理get_required_env(var_name, description)读取必填环境变量缺失或为空时抛出带描述信息的ValueError见 env_utils.py#L11-L35validate_env_vars(*var_names)批量校验多个变量一次性汇总全部缺失项get_env_with_default(var_name, default)带默认值的读取。input_validation.pyshared/python/input_validation.py输入校验与清洗validate_number_input(value, min_val1, max_val100, field_namenumber)将字符串安全转换为区间内的整数validate_text_input(value, max_length500, ...)文本长度校验与去空白sanitize_prompt_input(value, max_length1000, strictFalse)面向 LLM prompt 的防注入清洗——剥离空字节与控制字符移除模板注入{{...}}、变量替换${...}、script标签与javascript:URL可选strict模式仅保留安全字符并统一空白见 input_validation.py#L96-L151validate_email(email)、validate_url(url, require_httpsTrue)格式校验URL 默认强制 HTTPS。api_utils.pyshared/python/api_utils.py安全 API 请求封装make_safe_request(url, methodGET, timeout30, retries3, **kwargs)带超时、raise_for_status()与重试的请求包装失败后抛出RequestException见 api_utils.py#L15-L53create_openai_client(api_keyNone)从环境变量读取OPENAI_API_KEY并创建 OpenAI 客户端密钥缺失时给出明确报错create_azure_openai_client(endpointNone, api_keyNone)读取AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_API_KEY将base_url指向endpoint/openai/v1/——该 v1 端点同时服务于 Responses API因此无需api_version见 api_utils.py#L91-L144download_image(url, save_path, timeout30)安全下载图片并写入磁盘。2.3 建议的代码改进方向路线图指出以下长期目标其中类型提示已在shared/模块完成课程示例代码则刻意保持简单以降低学习门槛类型提示覆盖为所有 Python 文件补充类型提示在所有 TS 项目启用严格模式文档标准所有 Python 函数加 docstring所有 JS/TS 函数加 JSDoc测试框架pytest 配置与示例测试已完成见下节JestJS/TS配置仍待补充。3. 教育与测试基础设施从示例到可验证3.1 共享工具的测试套件已落地路线图中添加 pytest 配置与示例测试一项已实现测试代码位于 tests/ 目录并在 CI 中运行tests/conftest.py将仓库根目录插入sys.path保证shared.python包在任意工作目录下都能被导入tests/test_env_utils.py覆盖get_required_env返回正常值 / 缺失抛错 / 空值抛错 / 错误信息含描述、validate_env_vars返回映射 / 汇总报告缺失项、get_env_with_default默认值 vs 实际值使用monkeypatch模拟环境变量tests/test_input_validation.py以参数化方式验证validate_number_input的边界与非法输入、validate_text_input的长度上下限、sanitize_prompt_input对{{}}、${}、script、javascript:的剥离以及邮箱/URL 校验的正反用例tests/test_api_utils.py用monkeypatch替换requests.request验证make_safe_request的成功路径与重试次数retries3时恰好调用 3 次并验证两个客户端工厂在缺少密钥/端点时抛出带关键信息的ValueError。这些测试为课程代码的持续演进提供了回归保障也直接演示了面向教学代码如何写轻量级单元测试。3.2 新课程主题提案第 22–24 课提案课程覆盖内容22 · AI 应用安全提示词注入攻击与防御、API 密钥管理、内容审核、限流与滥用防护23 · 生产环境部署Docker 容器化、CI/CD 流水线、监控与日志、成本管理24 · 高级 RAG 技术混合检索关键词 语义、重排序策略、多模态 RAG、评估指标3.3 既有课程的改进建议课程建议改进06 · 文本生成增加流式streaming响应示例07 · 聊天应用增加对话记忆模式08 · 搜索应用增加向量数据库对比09 · 图像生成增加图像编辑/变体示例11 · 函数调用增加并行函数调用15 · RAG增加分块chunking策略对比17 · AI 智能体增加多智能体编排4. API 现代化4.1 已废弃 API 模式的迁移路线图列出了课程中需要更新的旧 API 调用模式。需要特别说明的是日文版文档记录了迁移计划英文原版 docs/ENHANCED_FEATURES_ROADMAP.md 已标注该项迁移完成因此这里展示的是一份现状对照表旧模式新模式影响范围openai.api_type azure/AzureOpenAI()chat 场景OpenAI(base_urlendpoint/openai/v1/)Responses APIPython chat 示例openai.ChatCompletion.create()/client.chat.completions.create()client.responses.create(input...)→response.output_text多个 Notebook 与脚本azure/openai的OpenAIClient.getChatCompletions()TypeScriptopenai包client.responses.create()→response.output_textTypeScript 示例df.append()pandaspd.concat()RAG Notebook迁移的边界条件值得注意使用azure-ai-inference/azure-rest/ai-inferenceSDKclient.complete()的 Microsoft Foundry 模型示例仍然保留 Model Inference API因为该 API 不支持 Responses API而AzureOpenAI()在 embeddings 与图像生成场景中依旧有效。这一取舍与 shared/python/api_utils.py 中create_azure_openai_client的实现相互印证——聊天场景统一走 v1 端点而专用场景保留原 SDK。4.2 待演示的新 API 能力结构化输出Structured OutputsJSON 模式以及严格 schema 下的函数调用视觉能力Vision基于 GPT-4o 的图像分析、多模态提示词Responses API 内置工具取代旧版 Assistants API代码解释器code interpreter、文件搜索file search、Web 搜索与自定义工具。5. 基础设施改进CI/CD 与安全扫描5.1 CI/CD 工作流英文原版路线图确认code-quality.yml已实现对受维护的shared/工具模块强制执行Python 的 Ruff Black 检查对其余课程代码以advisory建议性方式运行并对 JS/TS 执行建议性的 ESLint 检查。基线示例文档中的原始示意配置如下# .github/workflows/code-quality.yml name: Code Quality on: [push, pull_request] jobs: python-lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.10 - run: pip install ruff black mypy - run: ruff check . - run: black --check . js-lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx eslint .5.2 安全扫描工作流英文原版确认security.yml已实现针对 Python 与 JS/TS 的CodeQL 分析触发于 push、pull request 与每周定时任务并在 pull request 上执行依赖审查dependency review。基线示例# .github/workflows/security.yml name: Security Scan on: [push, pull_request] jobs: codeql: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: github/codeql-action/initv3 with: languages: javascript, python - uses: github/codeql-action/analyzev3 dependency-review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/dependency-review-actionv46. 开发者体验Dev Experience6.1 DevContainer 增强英文原版确认 DevContainer 已改进容器内置 Pylance、Black 格式化器、Ruff、ESLint、Prettier 与 Copilot 扩展开启保存即格式化format-on-save并绑定仓库的 Black/Prettier 配置同时安装开发工具ruff、black、mypy、pytest使本地可以复现 code-quality 工作流。由于mcr.microsoft.com/devcontainers/universal基础镜像已自带 Python 与 Node无需额外 features。路线图基线配置{ name: Generative AI for Beginners, image: mcr.microsoft.com/devcontainers/universal:2, features: { ghcr.io/devcontainers/features/python:1: { version: 3.11 }, ghcr.io/devcontainers/features/node:1: { version: 20 } }, customizations: { vscode: { extensions: [ ms-python.python, ms-python.vscode-pylance, ms-toolsai.jupyter, dbaeumer.vscode-eslint, esbenp.prettier-vscode, github.copilot ], settings: { python.formatting.provider: black, editor.formatOnSave: true } } }, postCreateCommand: pip install -e .[dev] npm install }6.2 交互式 Playground建议预填 API 密钥经环境变量注入的 Jupyter Notebook面向视觉学习者的 Gradio/Streamlit 演示用于知识评估的交互式测验。7. 多语言支持7.1 当前覆盖情况技术栈覆盖课程状态Python全部课程完成TypeScript06–09、11部分JavaScript06–08、11部分.NET/C#部分课程部分7.2 建议追加的技术栈Go—— 在 AI/ML 工具链中增长迅速Rust—— 面向性能敏感型应用Java/Kotlin—— 面向企业级应用。8. 性能优化8.1 代码级优化方向Async/Await 模式补充批处理的异步示例演示并发 API 调用缓存策略增加 embeddings 缓存示例介绍响应缓存模式Token 优化补充tiktoken使用示例演示 prompt 压缩技术。仓库 pyproject.toml 已将tiktoken0.5.0列入运行时依赖为这一方向提供了直接支撑。8.2 成本优化示例按任务复杂度选择模型通过提示词工程提升 token 效率批量操作的批处理示例。9. 可访问性与国际化9.1 翻译现状日文版文档中的语言覆盖表英语/简体中文/日语/韩语已完成西班牙语/葡萄牙语/土耳其语/波兰语部分完成反映的是早期状态。英文原版已更新为全部翻译完成由 Azure Co-op Translator本地化图片存放于 translated_images/。这一事实也可以直接从仓库结构得到印证——translations/与translated_images/下确实存在 ar、zh-CN、ja、ko、fr、de 等 50 语言目录。9.2 可访问性改进为所有图片补充替代文本alt text确保代码示例具备正确的语法高亮为所有视频内容增加文字转写色彩对比度符合 WCAG 指南。10. 实施优先级分阶段路线路线图将全部改进按时间窗口划分成四个阶段勾选状态反映英文原版的最新进度阶段 1立即响应第 1–2 周——全部完成修复关键安全问题添加代码质量配置创建共享工具模块文档化安全指南对应 docs/SECURITY_GUIDELINES.md阶段 2短期第 3–4 周——大部分完成更新废弃 API 模式Chat Completions → Responses APIPython TypeScript为所有 Python 文件添加类型提示shared/模块已完成课程示例保持简洁添加代码质量 CI/CD 工作流创建安全扫描工作流阶段 3中期第 2–3 个月——部分完成新增安全课程新增生产部署课程改进 DevContainer 配置添加交互式演示阶段 4长期第 4 个月起新增高级 RAG 课程扩展语言/技术栈覆盖建立全面的测试套件设立认证计划结论这份路线图为 Generative AI for Beginners 课程提供了一套可执行、可验证、分层级的改进方案紧急安全修复已全部落地并固化为 docs/SECURITY_GUIDELINES.md共享工具模块shared/python/ 的env_utils.py、input_validation.py、api_utils.py配齐了类型标注、docstring 与覆盖完整的测试tests/CI/CD 与安全扫描工作流、DevContainer 已实现API 调用已从旧式 Chat Completions 迁移至 Responses APIFoundry 示例按约束保留 Model Inference API。对于学习者与维护者而言这份文档的价值在于它把课程好不好这种主观问题转化成了可勾选的工程清单——从密钥管理、输入清洗、请求超时到 lint/格式化/类型检查/安全扫描再到教育内容与多语言覆盖任何开发者都可以对照 docs/ENHANCED_FEATURES_ROADMAP.md 与仓库实际代码快速定位某项最佳实践应该怎么写、写在哪、如何验证。如需参与改进可在仓库中按各章节标注的待办项提交 Issue 或贡献代码。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考