AI Agent / 系统课时
管理模型密钥与配置
管理模型密钥与配置
本课创建 model_config.py。接下来两课直接复用它。应用从进程环境读取服务地址、模型名和密钥,超时未设置时取 30 秒。
配置由运行环境提供
部署平台注入的值在 Python 中体现为进程环境变量。本例直接读取该环境。若将来给本地开发增加 .env,可让加载器在环境变量未设时补值,避免覆盖部署注入。仓库只保存空值或明确占位的配置示例。
| 变量 | 内容 |
|---|---|
MODEL_BASE_URL |
从服务文档核对过的 HTTPS 基地址,含版本路径,例如 https://provider.example/v1 |
MODEL_NAME |
当前账户可以调用的模型标识 |
MODEL_API_KEY |
由密钥管理器或当前运行环境提供 |
MODEL_TIMEOUT_SECONDS |
每次读取等待的上限,默认 30 秒 |
服务地址决定 Bearer 密钥会发往哪里。生产系统应由管理员固定信任的地址,禁止把用户、模型或检索结果提供的网址写进该配置。
在启动时校验
python
import math
import os
from dataclasses import dataclass, field
from urllib.parse import urlsplit
@dataclass(frozen=True)
class ModelConfig:
base_url: str
model_name: str
api_key: str = field(repr=False)
timeout_seconds: float = 30.0
def load_config(env=None):
env = os.environ if env is None else env
def required(name):
value = env.get(name, "").strip()
if not value or value.startswith("<") or value == "replace-with-your-key":
raise ValueError(f"{name} 必须明确配置")
return value
base_url = required("MODEL_BASE_URL")
try:
parsed = urlsplit(base_url)
valid_url = (parsed.scheme == "https" and parsed.hostname
and (parsed.port is None or 1 <= parsed.port <= 65535)
and parsed.username is None and parsed.password is None
and not parsed.query and not parsed.fragment)
except ValueError:
valid_url = False
if not valid_url:
raise ValueError("MODEL_BASE_URL 必须是无用户信息、查询和片段的 HTTPS 基地址")
try:
timeout = float(env.get("MODEL_TIMEOUT_SECONDS", "30"))
except ValueError:
raise ValueError("MODEL_TIMEOUT_SECONDS 必须是数字") from None
if not math.isfinite(timeout) or not 0 < timeout <= 120:
raise ValueError("MODEL_TIMEOUT_SECONDS 必须大于 0 且不超过 120")
return ModelConfig(
base_url=base_url.rstrip("/"),
model_name=required("MODEL_NAME"),
api_key=required("MODEL_API_KEY"),
timeout_seconds=timeout,
)
if __name__ == "__main__":
demo = {"MODEL_BASE_URL": "https://provider.example/v1",
"MODEL_NAME": "demo", "MODEL_API_KEY": "local-test-only"}
config = load_config(demo)
print(f"model={config.model_name}, timeout={config.timeout_seconds:g}, key_configured=True")运行 python model_config.py,结果为 model=demo, timeout=30, key_configured=True。将测试配置的超时设为 NaN 或删除密钥会明确失败。配置检查能确认本地参数完整,服务是否接受该密钥要到下一课调用时才知道。repr=False 只隐藏数据类的字符串表示。不要将整个配置序列化进日志。
按自己的节奏,确认真正理解。