搭建开发环境 · AI 工程课程

本课搭建后续课程共用的 Python 开发环境。先完成本地离线练习，再配置自己账号中的模型服务。

配套代码见 ai-engineering-bootcamp-prerequisites。建议动手逐步编写代码，不要只克隆仓库运行。

开发环境与 API 配置

搭建本地 Python 开发环境。
配置并测试 LLM API 密钥。

Streamlit 应用与容器部署

编写基础 Streamlit 前端应用。
使用 Docker 将应用打包为容器镜像，并通过 Docker Compose 启动部署。

FastAPI 后端服务

将 LLM 调用逻辑抽离至独立的 FastAPI REST 服务。
使用 Docker Compose 将后端作为独立服务部署。

前后端集成

改造 Streamlit 前端，改为通过 HTTP 调用已部署的 FastAPI 服务。
使用 Docker Compose 在独立容器中协同运行 FastAPI 与 Streamlit。

Python 环境配置步骤

步骤 1：检查 Python 版本

建议使用 Python 3.12；下载示例的依赖按 Python 3.11–3.13 配置。使用以下命令检查当前解释器版本：

python --version

步骤 2：安装依赖管理工具

课程项目统一使用 uv 管理 Python 依赖：

pip install uv

步骤 3：创建并激活虚拟环境

使用 uv 创建虚拟环境。以下激活命令适用于 macOS 和 Linux：

uv venv .venv --python 3.12
source .venv/bin/activate

Windows PowerShell 使用 .venv\Scripts\Activate.ps1 激活环境。也可以不激活环境，直接使用虚拟环境中的 Python 执行后面的命令。

步骤 4：选择 IDE 与开发工具

选择常用的 Python 集成开发环境（IDE）：

本地编辑器：VS Code，可按需安装 Python 与 GitHub Copilot 扩展；模型服务配置留在后端。
其他 IDE：PyCharm。

上述 IDE 均支持直接运行 Jupyter Notebook，也可以单独使用专用 Notebook 环境：

JupyterLab：在本地机器上统一管理数据资料、Notebook 与运行环境。

步骤 5：初始化版本控制

使用 Git 初始化本地仓库并提交初始代码：

git init
git add .
git commit -m "Initial project setup"

也可以先在 GitHub 上创建仓库，再通过 IDE 直接克隆到本地。

步骤 6：关联 GitHub 远程仓库

通过远程仓库备份代码并支持团队协作：

在 GitHub 上新建空仓库。
将本地仓库关联至远端并推送主分支：

git remote add origin <repository_url>
git branch -M main
git push -u origin main

步骤 7：安装 Docker 容器环境

使用容器化有助于保持开发与部署环境一致。按操作系统安装 Docker Desktop：

安装 Docker Desktop：
- 适用于 Windows 和 Mac 的 Docker Desktop
- 适用于 Linux 的 Docker Desktop

配置本地开发与模型接入

下载贯通示例与环境模板，解压后进入 cn-course-example 目录。先在该目录创建虚拟环境，再运行 uv pip install -r requirements-services.txt，随后用虚拟环境中的 Python 执行 python -m unittest test_pipeline.py test_services.py -v。这些测试使用离线 fixture，不需要真实模型或企业平台密钥；调用真实接口的步骤见包内 README。

本课程分别配置聊天、结构化输出、工具调用和向量嵌入四类能力，对应环境变量前缀 CHAT_、STRUCTURED_、TOOLS_、EMBEDDING_。每组单独填写 BASE_URL、API_KEY 和 MODEL；embedding 还需填写 EMBEDDING_DIMENSIONS。密钥只留在学习者自己的后端进程环境中；复制 .env.example 本身不会让 Python 自动加载这些值。

练习：记录本课使用的环境配置、测试输入、预期输出与异常失败分支，并使用脱敏数据完整复现流程。