Generative AI for Beginners 保加利亚语版课程导读：21 课学习地图、多语言机制与环境配置

本篇指南基于仓库中的 保加利亚语课程总览文档，系统讲解 Generative AI for Beginners（21 课入门课程）的课程结构与学习路径、多语言翻译体系（Co-op Translator + GitHub Actions 自动化）如何支撑 55 个语言的课程同步更新，以及如何用 sparse checkout 轻量克隆、选择 LLM 服务商并配置 .env 环境变量来跑通课程中的全部代码示例。

一、这份文档是什么：课程 README 的保加利亚语版本

translations/bg/README.md 是课程总 README 的保加利亚语（Български）官方翻译版。它与 英文原版 README 在结构上完全一一对应，覆盖同一套内容：

• 课程定位：由 Microsoft Cloud Advocates 出品的 21 课生成式 AI 入门课程（Version 3）；
• 多语言支持表与轻量克隆（sparse checkout）命令；
• 21 课的完整课程目录表（含每课的链接、简介、视频与延伸学习入口）；
• 课程前置条件、各 LLM 服务商的对应关系、社区支持与贡献方式。

值得注意的翻译机制细节：保加利亚语版文档末尾带有明确的 AI 翻译声明（CO-OP TRANSLATOR DISCLAIMER 注释块内），说明该文档由 AI 翻译服务 Co-op Translator 翻译生成，原文（英文）为权威版本，自动翻译可能包含误差。整个 translations/ 目录下的各语言 README 都由同一套 GitHub Action 流程自动维护，语言导航表位于 <!-- CO-OP TRANSLATOR LANGUAGES TABLE START/END --> 注释标记之间，标记外的内容是人工维护的。

从目录结构看，保加利亚语翻译并非只有这一个 README：translations/bg/ 下镜像了全部 22 个课程单元目录（00-course-setup 到 21-meta），每个单元都包含翻译后的 README.md 和对应的 Notebook，例如 保加利亚语版第 01 课、保加利亚语版课程安装指南。此外还同步翻译了 CONTRIBUTING.md、SECURITY.md、CODE_OF_CONDUCT.md、AGENTS.md 等项目文档。翻译后的配图则统一存放在 translated_images/bg/ 目录，为压缩后的 webp 格式并按语言分目录管理（这一点也记录在项目根的 AGENTS.md 中："Translated images stored in translated_images/ directory"）。

二、多语言体系：55 个语言子目录如何保持"永远最新"

文档开头的导航表由 GitHub Action 自动生成，覆盖阿拉伯语、孟加拉语、保加利亚语、缅甸语、简繁中文（含港、澳、台四个变体）、克罗地亚语、捷克语、丹麦语、荷兰语、爱沙尼亚语、芬兰语、法语、德语、希腊语、希伯来语、印地语、匈牙利语、印尼语、意大利语、日语、康纳达语、高棉语、韩语、立陶宛语、马来语、马拉雅拉姆语、马拉地语、尼泊尔语、尼日利亚皮钦语、挪威语、波斯语、波兰语、葡萄牙语（巴西/葡萄牙）、旁遮普语、罗马尼亚语、俄语、塞尔维亚语、斯洛伐克语、斯洛文尼亚语、西班牙语、斯瓦希里语、瑞典语、他加禄语、泰米尔语、泰卢固语、泰语、土耳其语、乌克兰语、乌尔都语、越南语等 47 个翻译语言入口。

结合仓库实际结构，当前 translations/ 下共有 55 个语言子目录（含英文原版 en 与 4 个中文区域变体 zh-CN/zh-HK/zh-MO/zh-TW），每个子目录包含 40 个 Markdown 文件与 28 个 ipynb Notebook；translated_images/ 下对应 55 个语言目录，每目录 145 张 webp 图片。保加利亚语版 README 中自称"超过 50 个语言翻译"，与实际目录规模一致。

这套多语言机制的落地保障来自仓库根目录的 CI 配置 validate-markdown.yml：

• 该工作流在针对 **.md / **.ipynb 的 PR 上触发，但通过 paths 配置明确排除了 !translations/** 与 !translated_images/**——即翻译内容不由上游仓库的 Markdown 校验流程约束，而是由翻译 Action 流水线独立生成；
• 校验内容包括：相对路径是否失效（check_broken_paths）、路径链接是否带统计参数（check_paths_tracking）、URL 是否带追踪参数（check_urls_tracking）、URL 是否携带地区 locale（check_urls_locale）、外链是否失效（check_broken_urls）。

这也解释了为什么保加利亚语版 README 中的图片引用是带哈希后缀的 webp 路径（如 translated_images/bg/repo-thumbnailv4-fixed.11f1ce6a85d01461.webp）：翻译流水线在生成各语言文档时同步处理图片，重命名为"原名 + 内容哈希 + .webp"并放到对应语言目录下，保证各语言站点的图片引用互不冲突。

三、轻量克隆：sparse checkout 绕过 50+ 语言的大仓库

由于多语言体系使仓库体积显著增大，文档给出了不带翻译的克隆方式——先做 blob 级懒加载克隆，再用 sparse-checkout 排除 translations 与 translated_images 两个大目录：

Bash / macOS / Linux：

git clone --filter=blob:none --sparse https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners
git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'

CMD（Windows）下引号写法略有不同：

git clone --filter=blob:none --sparse https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners
git sparse-checkout set --no-cone "/*" "!translations" "!translated_images"

命令原理：--filter=blob:none 让 git 不立即下载文件内容（blob 按需拉取），--sparse 配合 sparse-checkout set --no-cone 的精确路径规则只检出根目录下的课程目录（00-course-setup～21-meta）与英文文档，跳过的两个目录合计超过 5000 个文件（55 语言 × 68 个文档文件 + 55 语言 × 145 张图片），从而"以更快的下载速度获得完成课程所需的一切"。

四、课程结构：21 课 + 安装课，Learn 与 Build 两类标签

文档明确：本课程含 21 个课节（加上编号 00 的安装课共 22 个目录），每课主题独立、可从任意一课开始。课节分两类标签：

• Learn（Учене）：讲解生成式 AI 概念的课程；
• Build（Изграждане）：讲解概念并给出 Python 与 TypeScript 双语言代码示例的课程。

文档中逐课给出的完整课程目录如下（链接指向保加利亚语翻译版，英文原版路径将 translations/bg/ 换为课程目录即可）：

#	课程	类型	学习内容
00	课程安装	—	如何配置开发环境
01	生成式 AI 与 LLM 导论	Learn	理解什么是生成式 AI、LLM 如何工作
02	探索与比较不同 LLM	Learn	如何为场景选择正确模型
03	负责任地使用生成式 AI	Learn	如何负责任地构建生成式 AI 应用
04	提示工程基础	Learn	提示设计的实用最佳实践
05	高级提示技巧	Learn	应用提升提示质量的技巧
06	构建文本生成应用	Build	用 Azure OpenAI / OpenAI API 构建文本生成应用
07	构建聊天应用	Build	高效构建与集成聊天应用的技巧
08	构建基于向量数据库的搜索应用	Build	使用 Embeddings 做数据检索的搜索应用
09	构建图像生成应用	Build	图像生成应用
10	低代码 AI 应用	Build	用低代码工具构建 AI 生成应用
11	函数调用集成外部应用	Build	Function Calling 是什么及其应用场景
12	AI 应用的 UX 设计	Learn	在生成式 AI 开发中应用 UX 设计原则
13	保护你的生成式 AI 应用	Learn	AI 系统的威胁、风险与防护方法
14	生成式 AI 应用生命周期	Learn	LLM 生命周期管理与 LLMOps 的工具和指标
15	RAG 与向量数据库	Build	用 RAG 框架从向量数据库检索 Embeddings 的应用
16	开源模型与 Hugging Face	Build	使用 Hugging Face 上开源模型的应用
17	AI 智能体	Build	使用 AI Agent 框架的应用
18	LLM 微调	Learn	LLM 微调的内容、原因与方法
19	构建小型语言模型（SLM）	Learn	使用小型语言模型的优势
20	使用 Mistral 模型构建	Learn	Mistral 模型家族的特性与差异
21	使用 Meta 模型构建	Learn	Meta 模型家族的特性与差异

每课的标准配置在文档"每个课程包含"一节中列明：主题短视频导览、位于各课 README.md 中的文字教程、支持 Azure OpenAI 与 OpenAI API 的 Python/TypeScript 代码示例、以及"继续学习（Keep Learning）"延伸阅读区。从仓库结构可以看到 Build 类课程确实附带双语言示例，如 05 课 Python 示例与解答、05 课 JavaScript 示例、06 课 Azure OpenAI 应用脚本 等；部分课程还带 TypeScript 子项目（如 07 课 chat-completions-app）与 dotnet notebook。

五、前置条件与 LLM 服务商选择

文档给出的运行代码所需条件：

• LLM 服务商（三选一或多选），课程按文件名前缀区分服务商：
  • Azure OpenAI Service —— 对应文件名含 aoai-assignment 的课程；
  • GitHub Marketplace Model Catalog（Microsoft Foundry Models）—— 对应 githubmodels 前缀课程；
  • OpenAI API —— 对应 oai-assignment 前缀课程；
• 基础的 Python 或 TypeScript 知识（纯零基础可先补齐语言基础课）；
• 一个 GitHub 账号，用于 fork 整个仓库到自己的账号。

对应课程安装课 00-course-setup 中更详细的 服务商选型说明（03-providers.md） 补充了文档未展开的两个要点：

1. 文件名前缀与凭证的严格绑定：aoai（需 Azure OpenAI endpoint + key）、oai（需 OpenAI key）、hf（需 Hugging Face token）、githubmodels（需 Microsoft Foundry Models endpoint + key）。"你可以配置一个、全部或零个服务商，相关课程在缺少凭证时会直接报错"——这意味着学习路径是可选的，不必全部配置。
2. GitHub Models 的退役提示：英文主 README 与安装课文档均注明 GitHub Models（及其 GITHUB_TOKEN 变量）将于 2026 年 7 月底退役，替代方案为 Microsoft Foundry Models，这也是文档中 githubmodels 课程的现行配置路径。

关于 .env 配置的完整流程（创建 .env.copy 副本、cp .env.copy .env、填充各变量），以 00-course-setup/03-providers.md 为准，其变量清单为：

变量	说明
OPENAI_API_KEY	OpenAI 服务（非 Azure）的授权密钥
AZURE_OPENAI_API_KEY	Azure OpenAI 服务的授权密钥
AZURE_OPENAI_ENDPOINT	Azure OpenAI 资源已部署的端点
AZURE_OPENAI_DEPLOYMENT	文本生成（聊天补全）模型部署名，推荐 gpt-4o-mini
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT	文本向量化模型部署名，推荐 text-embedding-3-small
AZURE_INFERENCE_ENDPOINT	Microsoft Foundry 项目端点（Foundry Models 用）
AZURE_INFERENCE_CREDENTIAL	Microsoft Foundry 项目 API key
HUGGING_FACE_API_KEY	Hugging Face 访问令牌

在源码层面，课程对"缺少环境变量"这一最常见失败场景做了工程化处理：shared/python/env_utils.py 提供 get_required_env()、validate_env_vars() 与 get_env_with_default() 三个函数，当变量缺失或为空时抛出带明确指引的 ValueError（提示"请在 .env 文件或环境中设置"），并对多个变量做批量校验、一次性列出所有缺失项。该模块是仓库中受 CI 强制约束的"受维护共享工具"（见下文）。

六、仓库的工程化保障：CI 工作流与共享工具测试

保加利亚语 README 虽未展开，但仓库根目录的配置文件印证了课程代码示例的维护标准，可作为"这套课程示例为什么能长期可运行"的佐证：

• code-quality.yml 定义了三层质量门禁：
  • python-quality：Python 3.11 + ruff check shared/ 与 black --check shared/ 为强制项（共享工具模块必须保持干净），而全仓库范围的 ruff 检查为建议性（continue-on-error: true，注释明确"课程示例代码有意保持简单"）；
  • python-tests：安装 pytest openai requests python-dotenv 后运行 pytest tests/，对应 tests/ 下针对 shared/python 各模块（api_utils、env_utils、input_validation）的单元测试；
  • js-quality：Node 20 + ESLint 对 JS/TS 示例做建议性检查。
• validate-markdown.yml 保证课程文档中的相对路径、外链不失效（校验规则见上文），这也是多语言站点链接完整性的重要保障。

对于 .NET 开发者，文档指向了独立仓库 Generative AI for Beginners (.NET Edition)（外部链接，此处不展开）。

七、社区支持与参与贡献

文档的"获取帮助"与"贡献"部分给出三条路径：

1. 官方 Discord 社区：与同期学习者和其他开发者交流（Microsoft Foundry 官方服务器）；
2. 开发者论坛：产品反馈与开发问题（GitHub 上的 Microsoft Foundry Developer Forum）；
3. 开源贡献：发现拼写或代码问题可提 issue 或 pull request。值得注意的是，英文课程安装课 00-course-setup/README.md 中特别强调：翻译贡献不得使用机器翻译，须由社区验证，只建议在自己精通的语言上志愿参与翻译——这一点与保加利亚语版 README 底部"本文件由 AI 翻译服务生成、英文原文为权威版本"的免责声明共同构成了仓库对翻译质量的完整态度：机器翻译用于规模化覆盖（55 个语言），语言社区用于质量校验。

文档末尾还附有其他课程矩阵（LangChain 系列、Azure/Edge/MCP/Agents 系列、生成式 AI 多语言系列、ML/Data Science/AI/Cybersecurity/Web Dev/IoT/XR 基础系列、Copilot 系列），这些均为同一团队出品的姊妹课程，链接以仓库文档内标注为准。

八、从文档到实践的落地路线

结合以上信息，一个保加利亚语（或任意语言）学习者的完整落地路线是：

1. 用 sparse checkout 命令（第三节）克隆课程本体，或整仓克隆后直接浏览 translations/<你的语言>/；
2. 按 课程安装课（保加利亚语版）完成 fork 与开发环境配置，推荐 GitHub Codespaces 以避免依赖问题；
3. 依据 03-providers.md 选择至少一个 LLM 服务商，按 .env.copy 模板填充凭证；
4. 从第 01 课的 Learn 内容建立概念，再到第 06～09、15～17 课的 Build 内容跑通 Python/TypeScript 双语言示例，遇到凭证缺失时会收到 env_utils.py 抛出的明确报错提示；
5. 每课结尾的"Keep Learning"区域提供延伸材料。

这套"英文主干 + 55 语言自动镜像 + 图片同构翻译 + CI 链接完整性校验 + 共享工具强制质量门禁"的组合，是该课程仓库能长期保持多语言内容同步、链接不断裂、示例代码可运行的核心工程机制，也解释了本文档（保加利亚语版）与英文原版在结构上完全一致、在细节上仅做语言映射的原因。