第 03 课 | 环境搭建Python 3.12 UV 虚拟环境 项目骨架工欲善其事必先利其器。这节课我们把开发环境搭好项目骨架建好后面 49 课的代码都在这里长出来。为什么用 UV 而不是 venv先说一个你可能没听过但应该关注的工具UV。如果你之前用 Python 开发大概率是这样管理环境的python-mvenv .venv .venv\Scripts\activate pipinstallrequests pipinstallpandas# ... 等半天这套流程有几个让人头疼的问题慢。pip 安装依赖的速度说实话在 2026 年了还跟 2016 年差不多。装个 pandas 要等好几分钟装个 torch 能等到你怀疑人生。依赖解析不靠谱。有时候pip install装了一堆冲突的包报错信息长得像天书你根本不知道该怎么解决。迁移麻烦。你把项目拷到另一台机器上得重新pip install -r requirements.txt然后祈祷所有版本都兼容。换个操作系统更麻烦。UV 就是来解决这些问题的。它是 Astral 公司就是做 Ruff 那个超快 linter 的团队用 Rust 写的 Python 包管理器。有多快呢安装依赖比 pip 快10-100 倍依赖解析更准确不会装出冲突的包原生支持pyproject.tomlPython 官方推荐的配置格式自动生成uv.lock锁定文件确保环境可复现可以直接管理 Python 版本不需要你自己去下载 Python 安装包说白了UV 就是 Python 世界的「npm nvm」一个工具搞定包管理和版本管理。安装 UV在 Windows 上安装 UV 非常简单打开 PowerShell运行一行命令powershell-ExecutionPolicy ByPass-cirm https://astral.sh/uv/install.ps1 | iex安装完成后关闭并重新打开 PowerShell验证一下uv--version如果看到版本号输出比如uv 0.8.x就说明安装成功了。用 UV 安装 Python 3.12UV 最酷的功能之一是它能直接帮你安装 Python不需要你去 python.org 下载安装包。uv python install 3.12等几秒钟Python 3.12 就装好了。验证一下uv python list你应该能看到3.12.x在列表里标记为已安装。创建项目骨架现在来创建我们的项目。进入你想放项目的目录运行cd C:\你的工作目录 uv init ai-agent-tutorial--python 3.12 cd ai-agent-tutorial这条命令做了三件事创建了ai-agent-tutorial目录初始化了pyproject.toml配置文件指定了 Python 版本为 3.12接下来我们把项目目录结构调整成我们需要的样子ai-agent-tutorial/config.py统一配置logger.py日志模块core/Agent 核心引擎tools/工具集agents/Agent 实例data/数据目录web/Web 界面eval/评估框架.envAPI Key 配置pyproject.toml项目配置图 1项目目录结构在 PowerShell 中创建这些目录New-Item-ItemType Directory-Path core,tools,agents,data,web,eval-ForceNew-Item-ItemType File-Path core\__init__.py,tools\__init__.py,agents\__init__.py-Force添加依赖用 UV 添加项目依赖非常简单uv add python-dotenv uv add requests uv add richrich是一个让终端输出变漂亮的库后面我们会经常用到它来美化输出。添加完依赖后pyproject.toml会自动更新同时生成uv.lock文件锁定所有依赖的精确版本。配置模块config.py每个项目都需要一个统一的配置管理模块。我们把 API Key、模型选择、路径配置等都放在这里。# config.py - 统一配置管理importosfrompathlibimportPathfromdotenvimportload_dotenv# 加载 .env 文件中的环境变量load_dotenv()# 项目路径 PROJECT_ROOTPath(__file__).parent DATA_DIRPROJECT_ROOT/dataDATA_DIR.mkdir(exist_okTrue)# LLM 配置 # 支持多种后端ollama, openai, dashscopeLLM_BACKENDos.getenv(LLM_BACKEND,ollama)LLM_MODELos.getenv(LLM_MODEL,qwen2:7b)LLM_BASE_URLos.getenv(LLM_BASE_URL,http://localhost:11434/v1)LLM_API_KEYos.getenv(LLM_API_KEY,ollama)# Ollama 不需要真实 key# Embedding 配置 EMBEDDING_BACKENDos.getenv(EMBEDDING_BACKEND,local)EMBEDDING_MODELos.getenv(EMBEDDING_MODEL,BAAI/bge-large-zh-v1.5)# 爬虫配置 CRAWL_DELAYfloat(os.getenv(CRAWL_DELAY,2.0))# 请求间隔秒CRAWL_TIMEOUTint(os.getenv(CRAWL_TIMEOUT,30))# 请求超时秒# 日志配置 LOG_LEVELos.getenv(LOG_LEVEL,INFO)LOG_FILEPROJECT_ROOT/logs/app.logLOG_FILE.parent.mkdir(exist_okTrue)然后创建.env文件存放敏感信息这个文件不要提交到 Git# .env - 敏感配置不要提交到 GitLLM_BACKENDollamaLLM_MODELqwen2:7bLLM_BASE_URLhttp://localhost:11434/v1LLM_API_KEYollama# 如果用 OpenAI# LLM_BACKENDopenai# LLM_MODELgpt-4o-mini# LLM_BASE_URLhttps://api.openai.com/v1# LLM_API_KEYsk-your-key-here# 如果用通义千问# LLM_BACKENDdashscope# LLM_MODELqwen-plus# LLM_API_KEYsk-your-key-here再创建一个.env.example作为模板这个可以提交到 Git# .env.example - 配置模板LLM_BACKENDollamaLLM_MODELqwen2:7bLLM_BASE_URLhttp://localhost:11434/v1LLM_API_KEYollama日志模块logger.py统一日志很重要。你不想到处print调试信息到时候想关都关不掉。# logger.py - 统一日志模块importloggingimportsysfromconfigimportLOG_LEVEL,LOG_FILEdefget_logger(name:str)-logging.Logger:获取配置好的 loggerloggerlogging.getLogger(name)# 避免重复添加 handleriflogger.handlers:returnlogger logger.setLevel(getattr(logging,LOG_LEVEL))# 控制台输出console_handlerlogging.StreamHandler(sys.stdout)console_handler.setLevel(logging.INFO)console_formatlogging.Formatter([%(asctime)s] %(levelname)-7s %(name)s - %(message)s,datefmt%H:%M:%S)console_handler.setFormatter(console_format)logger.addHandler(console_handler)# 文件输出file_handlerlogging.FileHandler(LOG_FILE,encodingutf-8)file_handler.setLevel(logging.DEBUG)file_formatlogging.Formatter([%(asctime)s] %(levelname)-7s %(name)s:%(lineno)d - %(message)s,datefmt%Y-%m-%d %H:%M:%S)file_handler.setFormatter(file_format)logger.addHandler(file_handler)returnlogger验证环境写一个简单的测试脚本确认一切正常# hello.py - 环境验证脚本fromconfigimportLLM_BACKEND,LLM_MODEL,PROJECT_ROOTfromloggerimportget_logger loggerget_logger(hello)defmain():logger.info(*50)logger.info(AI Agent 教程 - 环境验证)logger.info(*50)logger.info(f项目根目录:{PROJECT_ROOT})logger.info(fLLM 后端:{LLM_BACKEND})logger.info(fLLM 模型:{LLM_MODEL})logger.info(环境验证通过!)logger.info(*50)if__name____main__:main()运行uv run python hello.py你应该看到类似这样的输出[15:30:00] INFO hello - [15:30:00] INFO hello - AI Agent 教程 - 环境验证 [15:30:00] INFO hello - [15:30:00] INFO hello - 项目根目录: C:\...\ai-agent-tutorial [15:30:00] INFO hello - LLM 后端: ollama [15:30:00] INFO hello - LLM 模型: qwen2:7b [15:30:00] INFO hello - 环境验证通过! [15:30:00] INFO hello - 看到「环境验证通过」就说明一切正常。环境迁移如何在其他机器上复现UV 最爽的一点就是环境迁移。假设你要把项目拷到另一台机器或者 Linux 服务器只需要# 1. 复制整个项目目录不包括 .venv# 2. 在目标机器上安装 UV# 3. 进入项目目录运行uv sync# 4. 完成所有依赖自动安装版本完全一致uv.lock文件锁定了所有依赖的精确版本uv sync会严格按照 lock 文件安装确保环境 100% 一致。不需要requirements.txt不需要手动管理版本。VS Code 配置建议推荐安装以下 VS Code 插件插件用途Python (Microsoft)Python 语言支持Pylance智能代码补全Ruff代码格式化超快Python Debugger调试支持Mermaid Preview预览 Mermaid 图表在 VS Code 中选择 Python 解释器时选择 UV 创建的虚拟环境CtrlShiftP → Python: Select Interpreter → 选择 .venv 中的 Python小结与预告这节课我们把开发环境搭好了UV管理 Python 版本和依赖比 venv pip 快 10-100 倍项目骨架建好了后面 49 课的代码都在这里长出来配置模块统一了 LLM、Embedding、爬虫等配置日志模块统一了日志输出格式环境迁移只需uv sync一键搞定下一节课我们要在 RTX 3090 上部署本地大模型。用 Ollama 跑 Llama 3 和 Qwen2让你的代码拥有「大脑」。我们下一课见。系列教程导航上一篇第 02 课 | 三大业务场景总览竞品监控、数据问答、决策支持下一篇第 04 课 | 本地模型部署用 Ollama 在 RTX 3090 上运行 Llama 3 和 Qwen2本系列共 50 课持续更新中。关注我不迷路。