generative-ai-for-beginners 增强功能路线图从安全修复到代码质量体系的落地实践【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/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_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/已修复可以从源码中逐项验证这些已修复声明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.pydef make_safe_request(url, methodGET, timeout: int 30, retries: int 3, **kwargs): # 每次请求强制携带 timeout失败后重试重试耗尽抛出 RequestException for attempt in range(retries): try: response requests.request(methodmethod, urlurl, timeouttimeout, **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 [ openai1.0.0, python-dotenv1.0.0, requests2.31.0, azure-ai-inference1.0.0b1, tiktoken0.5.0, ] [project.optional-dependencies] dev [black24.0.0, isort5.13.0, mypy1.8.0, ruff0.2.0, pytest8.0.0, pytest-cov4.1.0]注意tiktoken已被列为正式依赖——这正是文档第 8.1 节token 优化tiktoken 示例的落地伏笔学生可以直接在课程代码中做分词计数与提示词压缩实验。各工具配置段的实际取值[tool.black]line-length 100目标py310–py312排除node_modules、.venv等目录[tool.ruff]line-length 100、target-version py310lint 规则集为E/W/F/I/B/C4/UP/S——其中Sflake8-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 --tbshort。shared/python 共享工具模块三个文件的职责与实现文档第 2.2 节预告的shared/python/模块如今包含三个文件每个都带有完整的 docstring 与可运行的 doctest 示例1. env_utils.py —— 环境变量安全读取get_required_env(var_name, descriptionNone)变量缺失或为空时抛出带指引信息的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_val1, max_val100)带区间的整数校验异常信息包含字段名validate_text_input(value, max_length500, min_length1, allow_emptyFalse)长度与空值约束sanitize_prompt_input(value, max_length1000, strictFalse)核心函数。它先剔除空字节与控制字符再按正则删除四类注入模式——模板注入{{...}}、变量替换${...}、script标签、javascript:URLstrictTrue时仅保留字母数字、空格与基础标点最后归一化空白并做长度断言validate_email/validate_url(require_httpsTrue)格式校验URL 默认只放行 HTTPS。这些函数把 13-securing-ai-applications 一课讲授的提示注入防护概念变成了可复制的代码原语。3. api_utils.py —— 安全 API 封装除前文提到的make_safe_request外还有三个工厂/工具函数create_openai_client(api_keyNone)未显式传 key 时读取OPENAI_API_KEY缺失即抛ValueError避免空 key 静默透传到 SDKcreate_azure_openai_client(endpointNone, api_keyNone)读取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, timeout30)复用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 的monkeypatchfixture 操控环境变量不污染真实环境这一写法本身也是给学生的示范。Jest 一侧的配置文件尚未在仓库中出现属于文档中的规划项。API 现代化从旧式调用到新客户端模型文档第 4.1 节给出了一张弃用 API 对照表指出课程脚本需要迁移的三类旧模式旧模型新模型受影响文件openai.api_type azureAzureOpenAI()客户端08-building-search-applications/中多个脚本openai.ChatCompletion.create()client.chat.completions.create()多个 notebookdf.append()pandaspd.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_VERSION2024-10-21仍保留为注释默认值供仍需旧版 REST 风格的脚本使用。也就是说新客户端模型已经是共享库的默认姿势而旧式散落脚本如 08 课脚本、RAG notebook的逐文件迁移是阶段 2 的未完成事项。基础设施与开发体验路线图建议 vs 仓库现状CI/CD 工作流规划中文档第 5 节给出了两个完整的工作流定义作为推荐配置code-quality.ymlpython-lint 作业setup-pythonv5 3.10 ruff check . black --check .js-lint 作业Node 20 npm cinpx eslint .与security.ymlCodeQL 分析 javascript/python dependency-review-actionv4。这两份 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.shVSCode 扩展清单与推荐列表基本一致ms-python.python、ms-python.vscode-pylance、ms-toolsai.jupyter、ms-python.black-formatter、charliermarsh.ruff、dbaeumer.vscode-eslint、esbenp.prettier-vscode、github.copilot并按文件类型分别指定了 BlackPython与 PrettierJS/TS作为默认格式化器。可以推断路线图推荐配置与现行配置在意图上完全一致差异仅在镜像版本与初始化脚本细节上。环境变量模板与配置基线.env.copy 模板体现了缺少环境变量校验修复后的配置基线涵盖四组凭据OpenAIOPENAI_API_KEYAzure OpenAIMicrosoft FoundryAZURE_OPENAI_API_VERSION、AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_DEPLOYMENT、AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTMicrosoft Foundry Models多供应商模型目录AZURE_INFERENCE_ENDPOINT、AZURE_INFERENCE_CREDENTIALHugging FaceHUGGING_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/子目录建议新增语言GoAI/ML 工具链增长、Rust性能关键场景、Java/Kotlin企业应用。性能与成本优化建议文档第 8 节提出三条代码级优化路径与一组成本示例方向Async/Await批量处理的异步示例、并发 API 调用演示缓存策略embedding 缓存、响应缓存模型token 优化结合tiktoken做分词统计与提示词压缩——注意tiktoken0.5.0已在 pyproject.toml 中成为正式依赖是三条建议中最接近落地的一条成本示例按任务复杂度选模型、面向 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 与安全扫描工作流则是当前最值得关注的后续演进方向。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考