理论部分

写大模型应用，最常见的“第一道坎”不是算法，而是环境与配置。一个可复现的项目通常需要三件事：

• 隔离的 Python 环境：避免“这台电脑能跑、那台电脑不能跑”的依赖冲突
• 统一的依赖清单：用 requirements.txt 固定依赖范围
• 安全的密钥管理：API Key 永远不要写死在代码里，使用 .env / 环境变量读取

本项目使用的配置方式是：用 .env 保存敏感信息，再用 python-dotenv 读取；调用模型侧使用 openai SDK（因为部分厂商兼容 OpenAI 协议，这样后续切换模型平台成本更低）。

---

实践部分

本案例做什么

1. 创建并激活虚拟环境
2. 安装项目依赖
3. 配置 .env，并用一段最小 Python 代码验证配置是否生效

1）创建虚拟环境并激活

在项目根目录执行：

python3 -m venv .venv
source .venv/bin/activate

如果是 Windows：

python -m venv .venv
.\.venv\Scripts\activate

2）安装依赖

pip install -r requirements.txt

依赖文件位于项目根目录：requirements.txt

3）配置 .env

项目提供了模板文件：.env.example

我们需要在项目根目录新建 .env 文件（或复制 .env.example 并改名为 .env），然后填入真实 Key：

ZHIPUAI_API_KEY=你的真实Key
ZHIPUAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4/

4）验证配置是否生效（主要代码）

把下面代码保存为 check_env.py（放在项目根目录即可），用于验证环境变量读取是否正常：

import os

from dotenv import load_dotenv


def mask_secret(value: str, left: int = 4, right: int = 4) -> str:
    if not value:
        return ""
    if len(value) <= left + right:
        return "*" * len(value)
    return f"{value[:left]}{'*' * (len(value) - left - right)}{value[-right:]}"


def main() -> None:
    load_dotenv()

    api_key = os.getenv("ZHIPUAI_API_KEY", "")
    base_url = os.getenv("ZHIPUAI_BASE_URL", "")

    if not api_key:
        raise RuntimeError("未检测到 ZHIPUAI_API_KEY，请检查 .env 是否存在且已填写")

    print("✅ 环境变量加载成功")
    print(f"ZHIPUAI_BASE_URL = {base_url or '(未设置)'}")
    print(f"ZHIPUAI_API_KEY  = {mask_secret(api_key)}")


if __name__ == "__main__":
    main()

5）运行结果

在虚拟环境已激活的前提下执行：

python3 check_env.py

运行后会看到类似输出（Key 会被打码）：

✅ 环境变量加载成功
ZHIPUAI_BASE_URL = https://open.bigmodel.cn/api/paas/v4/
ZHIPUAI_API_KEY  = abcd****************wxyz

如果出现报错：

• 未检测到 ZHIPUAI_API_KEY：检查 .env 是否放在项目根目录、变量名是否写对、是否忘了填值
• ModuleNotFoundError: No module named 'dotenv'：说明依赖没装成功，重新执行 pip install -r requirements.txt

---

总结

这一篇我们完成了“可复现开发环境”的搭建：虚拟环境、依赖安装、以及 .env 配置验证。