企业官网建设流程全解析

• 教程
• 人工智能
• 机器学习
• 深度学习

AI-For-Beginners 是一套面向初学者的 12 周、24 课人工智能课程，包含大量可执行的 Jupyter Notebook、测验与实验，覆盖 TensorFlow、PyTorch 以及 AI 伦理等内容。本篇指南以仓库内维护的官方故障排查手册为核心（芬兰语译本见 translations/fi/troubleshoot.md，英文原版见 troubleshoot.md），系统梳理学习者在克隆仓库、搭建 Python 环境、运行 Notebook、使用在线教材以及参与开源贡献过程中最常遇到的 10 类问题，并逐条给出症状、成因与可复现的解决方案。读完本文，你将掌握一套"诊断 → 定位 → 修复"的完整排障方法，能够独立处理从fatal: repository not found到 kernel 崩溃的绝大多数环境问题。

目录

• 仓库克隆问题
• 安装阶段问题
• 配置问题：环境变量
• 运行 Notebook 的问题
• 性能问题
• 在线教材网站问题
• 参与贡献时的问题
• 常见问题 FAQ
• 获取帮助的渠道

一、仓库克隆问题（Repository Not Cloning Properly）

背景：克隆是将整个仓库复制到本地机器的第一步。AI-For-Beginners 仓库体量较大——它内置了 50+ 种语言的翻译目录（见根目录 README.md 中的多语言支持列表），因此克隆方式的选择直接影响下载速度与成功率。

典型症状：

• fatal: repository not found：仓库地址错误或仓库不存在。
• Permission denied (publickey)：使用了 SSH 协议但本机未配置 SSH 公钥，或该账号没有仓库访问权限。

可能成因：

• 仓库 URL 拼写错误（大小写、路径、组织名不正确）。
• 账号权限不足（只读权限或未登录）。
• SSH 密钥未生成、未添加到 GitHub 账号，或未通过ssh-agent加载。

解决方案：

1. 核对仓库 URL，优先使用 HTTPS 协议。HTTPS 方式无需提前配置密钥，输入用户名与 Personal Access Token（或密码）即可完成克隆，是新手最稳妥的选择。
2. SSH 失败时切换回 HTTPS。如果克隆时看到Permission denied (publickey)，通常意味着 SSH 密钥环节出了问题，直接用 HTTPS 地址替代即可绕过该环节。
3. 可选：正确配置 SSH 密钥。如需长期使用 SSH 协议，需在本地生成密钥对、把公钥注册到账号，并通过ssh-agent加载私钥后再重试。

仓库级提示：利用稀疏检出（sparse checkout）加速克隆

由于仓库包含translations/与translated_images/两大目录（前者含各语言 Markdown 与 Notebook，后者含各语言图片），全量克隆下载量很大。根目录 README.md 官方推荐用"部分克隆 + 稀疏检出"只拉取课程本体：

git clone --filter=blob:none --sparse <仓库地址> cd AI-For-Beginners git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'

Windows CMD 下语法略有不同（将单引号改为双引号、去掉反斜杠），效果一致。这样你得到的是完成课程所需的全部内容，且下载速度显著提升。

二、安装阶段问题（Installation Issues）

本仓库依赖 Python 与大量第三方库。从 requirements.txt 可以看到课程用到的核心依赖被精确固定了版本，例如gensim==4.3.3、gym==0.26.2、keras==3.13.2、tensorflow==2.17.0、pandas==2.2.2、pillow==12.2.0、torchinfo==1.8.0、tqdm==4.66.5等，涉及 NLP（gensim、nltk、tokenizers）、强化学习（gym、pygame）、深度学习（tensorflow、keras、tensorboard、huggingface）与图像处理（imageio、scikit-image、seaborn）多个领域。因此"环境装不干净"是后续一切 Import 错误的根源。

问题 2：Python 环境报错

症状：

• ModuleNotFoundError: No module named '<package>'
• 运行脚本或 Notebook 时出现 ImportError

成因：依赖未安装，或 Python 版本不匹配。

解决方案：

1. 创建独立的虚拟环境，避免污染系统 Python：

   python -m venv venv source venv/bin/activate # Windows 下为 venv\Scripts\activate

2. 安装依赖：

   pip install -r requirements.txt

3. 核对 Python 版本。官方手册要求 Python 3.7 及以上：

   python --version

仓库级深化：推荐使用 conda 环境

lessons/0-course-setup/how-to-run.md 给出了更省心的官方路径：安装miniconda，然后用仓库提供的 environment.yml 一键创建名为ai4beg的完整环境。该文件同时声明了 conda 侧依赖（ipykernel、ipywidgets、jupyter、matplotlib=3.9、numpy=1.26、scikit-learn、scipy=1.13、opencv、PyTorch 全家桶等）与 pip 侧依赖（通过-r requirements.txt引用同一份 pip 清单），并指定了conda-forge与pytorch频道：

conda env create --name ai4beg --file environment.yml conda activate ai4beg

对比可见，Binder 云端环境使用的是 binder/environment.yml（版本更早的固定快照，Python 3.8.12、PyTorch 1.11.0），而当前仓库根目录的 environment.yml 是较新的版本组合——如果你同时在本机与 Binder 之间切换，留意两套环境的版本差异即可，无需手动修改仓库文件。

问题 3：Jupyter 未安装

背景：Notebook（.ipynb）是这套课程的核心学习载体，12 个模块的每个单元都配了可执行 Notebook。

症状：

• jupyter: command not found
• Notebook 无法启动

成因：Jupyter 未安装，或未安装到当前激活的虚拟环境中。

解决方案：

# pip 方式 pip install notebook # Anaconda/conda 方式 conda install notebook

安装完成后启动：

jupyter notebook

仓库级提示：如果你使用 environment.yml 创建的ai4beg环境，Jupyter 已作为依赖被自动安装（该文件包含jupyter与ipykernel），可跳过手动安装步骤。另外，使用 VS Code 打开仓库并安装 Python 扩展后，可以直接在编辑器内选择ai4beg内核运行 Notebook，详见 lessons/0-course-setup/how-to-run.md。

问题 4：依赖版本冲突

背景：当本机已装有较旧或相互矛盾的包时，即使pip install -r requirements.txt执行成功，import 阶段仍可能抛出版本不兼容错误或警告。

症状：关于包版本不兼容的报错或警告（例如tensorflow与keras、numpy与scikit-image之间的 ABI 不匹配）。

成因：旧的 Python 包与课程要求的版本冲突。

解决方案：

1. 在干净环境中安装：删除旧的 venv/conda 环境，重新创建。这是消除"历史遗留污染"最有效的手段。

2. 严格使用仓库锁定的精确版本：

   pip install -r requirements.txt

   若仍失败，按 README.md 的指引手动补齐缺失包。注意各语言子目录还有更细粒度的依赖清单，例如 NLP 模块提供了 lessons/5-NLP/requirements-pytorch.txt 与 lessons/5-NLP/requirements-tf.txt，可按所选框架按需安装。

三、配置问题：环境变量（Configuration Issues）

问题 5：环境变量未设置

背景：课程中的部分模块可能需要 API 密钥、Token 或其他配置项才能运行（例如需要下载预训练模型、调用外部服务的示例）。

症状：

• 运行时报KeyError
• 出现"缺少配置"的警告

成因：必需的os.environ变量未被赋值。

解决方案：

1. 查找仓库内是否提供.env.example或类似模板文件，以此确认需要哪些变量名。
2. 复制为.env并填入真实值（密钥、Token 等）。
3. 设置环境变量后重启终端或 IDE，确保新值被进程重新加载，再运行 Notebook。

四、运行 Notebook 的问题（Running Notebooks）

问题 6：Notebook 打不开或无法运行

背景：Jupyter Notebook 需要正确安装并绑定浏览器环境。

症状：

• Notebook 无法启动。
• 浏览器没有自动弹出。

成因：Jupyter 未安装，或浏览器配置异常。

解决方案：

1. 若 Jupyter 缺失，先按上文"问题 3"完成安装。
2. 手动打开 Notebook：从终端输出的日志中复制访问地址（形如http://localhost:8888/?token=...），手动粘贴到浏览器地址栏打开。Token 认证是 Jupyter 默认的安全机制，地址中的token=...参数即为当前会话凭证。

问题 7：Kernel 崩溃或卡死

背景：Notebook 的 kernel 可能因资源限制或代码错误而崩溃。

症状：

• Kernel 反复死亡或自动重启。
• 内存溢出（Out-of-Memory）错误。

成因：

• 加载了过大的数据集（例如训练全量 MNIST，见 data/mnist.pkl.gz 对应的原始数据规模）。
• 代码或包与当前环境不兼容。

解决方案：

1. 重启 Kernel：使用 Jupyter 界面中的 "Restart Kernel" 按钮，丢弃异常内存状态后从头执行。
2. 检查内存占用：关闭无关应用程序，为训练释放 RAM。
3. 改用云平台运行：将 Notebook 上传到 Google Colab 等托管环境，借助云端资源与独立内核规避本机资源瓶颈。

仓库级提示：官方运行指南 lessons/0-course-setup/how-to-run.md 提供了多种运行形态的取舍建议——本机（miniconda + VS Code）、浏览器（jupyter notebook或jupyterhub）、容器（.devcontainer）、云端 Binder、以及带 GPU 的云端方案。其中 Binder 有两点需要特别留意：其一，为了防止滥用，Binder 屏蔽了部分外部网络资源，导致需要联网下载模型或数据集的代码可能失败；其二，Binder 提供的算力较基础，课程后期的复杂训练会明显变慢。这也解释了为什么"Kernel 崩溃/卡死"与"运行缓慢"在本课程场景下格外常见。

五、性能问题（Performance Problems）

问题 8：Notebook 运行缓慢

背景：部分 AI 任务对内存与 CPU 的要求很高，尤其是课程后期的神经网络训练。

症状：

• 单元格执行极慢。
• 笔记本风扇高速运转。

成因：

• 数据集或模型规模过大。
• 本机资源有限。

解决方案：

1. 改用云平台：把 Notebook 上传到 Colab 等平台运行，利用云端算力。
2. 缩小数据集：练习阶段使用子采样/样例数据（sample data）即可验证流程，不必全量训练。
3. 关闭无关程序：释放系统内存，为 kernel 留出空间。

仓库级提示：课程后期（如 Transformers、GANs 等模块）对 GPU 的需求明显，官方在 lessons/0-course-setup/how-to-run.md 中建议使用带 GPU 的云环境（如 NC 系列虚拟机、Azure ML Notebook 或 Colab 的免费 GPU）。同时需注意部分订阅（如 Azure for Students）默认不提供 GPU，需要额外申请配额。

六、在线教材网站问题（Textbook Website Problems）

问题 9：章节无法加载

背景：课程可通过 Docsify 生成在线教材页面，按章节（lesson）组织展示各模块内容。

症状：某个章节（例如 Transformers/BERT 章节）在教材网站上缺失或打不开。

已知问题（记录于排查手册）：曾被社区报告的典型案例是"18 Transformers/BERT 章节无法在教材网站打开"，根因是章节文件命名错误——误把README.md写成了READMEtransformers.md。教材站点按约定文件名（README.md）扫描章节，命名不一致时该章节就不会出现在页面中。当前仓库中正确的章节文件位于 lessons/5-NLP/18-Transformers/README.md（以及各语言的对应翻译目录）。

解决方案：

1. 核对文件命名：作为贡献者，务必确保每个章节目录下的主文档命名为README.md，与站点扫描约定一致。
2. 上报缺失文件：若发现章节缺失，按章节名与错误细节提交 issue，便于维护者定位。

仓库级提示：官方教材站点由 lessons/0-course-setup/setup.md 描述的 Docsify 驱动。想在本机复现站点并验证章节是否完整，可 fork 仓库后在根目录执行docsify serve，站点会运行在localhost:3000；课程另有 PDF 版供离线阅读（见 etc/pdf/readme.pdf）。若某个章节在 Docsify 中缺失，多半同样是文件名不符合README.md约定的问题。

七、参与贡献时的问题（Contributing Issues）

问题 10：PR 未被接受或构建失败

背景：本仓库欢迎翻译、课程修正与格式修正等各类贡献，但所有贡献需通过检查并遵守贡献规范。

症状：

• Pull Request 被拒绝。
• CI/CD 流水线报错。

成因：

• 测试未通过。
• 未遵循代码或文档规范。

解决方案：

1. 通读贡献指南：以 CONTRIBUTING.md 与 etc/CONTRIBUTING.md 为准。前者明确了贡献类型（修正笔误/代码错误、提交翻译）与流程：fork 仓库 → 修改 → 提交带清晰描述的 PR；翻译需放入 translations/ 目录并按既有语言目录命名（如translations/es/、translations/zh-CN/）。后者则列出了项目当前重点征集贡献的方向（如深度强化学习章节、目标检测章节、PyTorch Lightning 示例、命名实体识别、自训练词向量等）。
2. 推送前在本地自测：至少确保你修改过的 Notebook 或 Markdown 能被正常加载、无语法错误。
3. 遵守格式要求：检查 lint 规则与排版约定，保持与现有文件一致的风格。

仓库级提示：翻译类贡献还涉及测验应用的联动。根据 etc/quiz-app/README.md，新增语言需在测验应用的assets/translations下建立对应目录、更新index.js导入与App.vue语言下拉框，并在翻译后的课程中通过?loc=xx查询参数链接本地化测验。也就是说，一次完整的翻译贡献可能同时涉及 translations/、translated_images/ 与 etc/quiz-app/ 三处改动，提交前请一并核对。

八、常见问题 FAQ

Q：如何获取某个具体模块的帮助？

每个模块通常自带 README，例如 lessons/2-Symbolic/README.md、lessons/4-ComputerVision/README.md、lessons/5-NLP/README.md 等。安装与使用类问题应首先从对应模块的 README 开始查起，其中往往包含了该模块特有的数据集、依赖与运行说明。

Q：如何报告 bug 或请求新功能？

带着清晰的描述与可复现步骤提交 issue。所谓"可复现步骤"至少应包含：运行环境（Python 版本、conda/pip 依赖版本、操作系统）、出错的 Notebook 路径（如 lessons/3-NeuralNetworks/03-Perceptron/ 下的.ipynb）、完整错误堆栈与已尝试的修复手段。

Q：我的问题不在列表中，可以求助吗？

可以。先检索仓库 issues 看是否已有相同问题；若没有，再新建 issue 说明你的具体情况。提问时附上本指南"问题 10"中列出的排查信息，能显著提高被解决的速度。

九、获取帮助的渠道（Getting Help）

• 查 issues：先在既有 issue 列表中检索关键词，避免重复提问，也能直接看到已知问题（如教材网站章节缺失类问题）的进展。
• 提问：使用仓库的 Discussions 讨论区提问，或为确认的新问题提交 issue。
• 社区：README 首页列出的社区沟通入口（如 Discord 服务器、Gitter 频道）可用于与维护者和其他学习者实时交流，详见根目录 README.md。

附：仓库排障速查表

最后提示：本指南面向的学习场景是"使用并参与维护 AI-For-Beginners 课程仓库"。仓库是只读的，你只需在自己的 fork 或本地副本中按上述步骤创建环境、运行 Notebook 与提交贡献，无需也不能改动当前仓库文件。遇到上表中未覆盖的新问题时，带上环境信息、Notebook 路径与完整报错去 issues/discussions 提问，是最快获得帮助的方式。

• 教程
• 人工智能
• 机器学习
• 深度学习