python配置文件YAML详解（含示例）

496人浏览 · 2026-03-15 16:42:40

· 2026-03-15 16:42:40 发布

基本规则：

python 读取 yaml 文件的常用方法

YAML 是 Python 项目中最常用的配置文件格式，所有参数集中定义在 YAML 里。YAML 以键值对为基础，通过缩进实现嵌套，支持列表、字典、锚点复用。Python 文件通过读取 YAML 文件解析出参数字典，再在代码中调用这些参数。

基本规则：

大小写敏感：ModelPath 和 modelpath 是两个不同参数；
缩进表示层级关系：仅支持空格（推荐 2 个空格），禁止 Tab（会报错）；
键值对核心：键: 值 格式，冒号后必须加空格；
注释：# 后加注释内容，注释内容不会被解析；
数据类型：支持字符串、数字、布尔值、列表、字典、空值等，无需显式声明类型。

安装PyYAML依赖：

pip install pyyaml  # 基础版
pip install pyyaml ruamel.yaml  # 进阶版（支持YAML 1.2、注释保留）

不同版本差异：PyYAML 是 Python 操作 YAML 的核心库，主要分为 5.x 系列（主流）和 3.x 系列（老旧）。YAML 1.2 是 2009 年发布的最新标准（1.1 是 2005 年版本），PyYAML 5.x+ 兼容两个版本

版本特性	PyYAML 3.x（Python2 时代）	PyYAML 5.x+（Python3 主流）	补充说明
Python 版本支持	仅 Python2（部分兼容 3.5-）	Python3.6+（推荐 3.8+）	3.x 已停止维护，不要使用
安全机制	无 `safe_load` 核心方法	新增 `safe_load()`	`load()` 有代码注入风险，必用 `safe_load()`
YAML 语法支持	仅 YAML 1.1	兼容 YAML 1.1/1.2	1.2 是最新标准，支持更多类型
数据类型解析	布尔值支持 `True/False`	仅识别小写 `true/false`	5.x 中 `True` 会被解析为字符串！
性能	无优化	新增 C 扩展加速	5.4+ 解析速度提升 2-3 倍
第三方依赖	无	可选依赖 `libyaml`	安装 `libyaml` 后性能更高

PyYAML核心方法：

方法	作用	安全风险	适用场景/关键参数
`yaml.load()`	解析 YAML 为 Python 对象（支持自定义类型）	高（代码注入）	仅本地可信配置，禁止用于外部输入
`yaml.safe_load()`	仅解析 YAML 基础类型（str/int/list/dict）	无	99% 的配置文件场景（必用），`safe_load` 无额外参数，仅依赖文件对象
`yaml.dump()`	Python 对象 → YAML 字符串（支持自定义类型）	中	同 `safe_dump`，但有安全风险
`yaml.safe_dump()`	Python 基础类型 → YAML 字符串	无	`default_flow_style`：是否单行显示`allow_unicode`：是否支持中文 `sort_keys`：是否排序键

核心语法：

1.基础数据类型

创建 basic_types.yaml:

# 1. 字符串（引号可选，含特殊字符/空格时必加）
model_name: project1        # 无引号（无特殊字符推荐无引号）
model_path: "/data/models/7b"     # 单引号/双引号必加（含特殊字符/）

    # | 和 > 是 YAML 中多行字符串的两种表示方式，核心区别是对「换行符」的处理：

prompt: |                         # 多行字符串（保留换行符和末尾空行）
  You are a memory expert.
  Task: {task}
  Memories: {memories}
short_prompt: >             # 折叠换行，将连续换行替换为单个空格，仅保留显式空行；
  This is a long prompt     # This is a long prompt but will be folded into a single line.
  but will be folded into 
  a single line.

# 2. 数字（整数/浮点数）
train_epochs: 10                  # 整数
learning_rate: 1e-5               # 浮点数（科学计数法）
batch_size: 32.0                  # 浮点数（自动识别）

# 3. 布尔值（小写！true/false，不是True/False）
use_vllm: true
enable_log: false

# 4. 空值（null/~ 均可）
cache_path: null                  # 禁用缓存
temp_dir: ~                       # 等价于 null

# 5. 时间（自动解析为字符串，需手动转换为datetime）
train_start_time: 2026-03-15 09:00:00

python读取示例：

import yaml

# 读取YAML文件
with open("basic_types.yaml", "r", encoding="utf-8") as f:
    config = yaml.safe_load(f)

# 调用参数
print("模型名称：", config["model_name"])          # 输出：project1
print("多行Prompt：", config["prompt"])           # 保留换行的完整字符串
print("是否启用vLLM：", config["use_vllm"])       # 输出：True
print("空值：", config["cache_path"])             # 输出：None

复杂数据结构（列表/字典）：

对应 Python 中 list 和 dict，创建 complex_structures.yaml：

# 1. 列表（数组）：- 开头，支持单行/多行
# 方式1：多行列表（推荐，易读）
retrieval_top_k:
  - 10    
  - 5     
  - 3    

# 方式2：单行列表（简写）
gpu_ids: [0, 1, 2, 3]

# 2. 嵌套字典（层级配置）
project1:
  actor:  # 第一层嵌套
    model_path: "/data/actor"
    hyper_params:  # 第二层嵌套
      temperature: 0.1
      top_p: 0.9
  ref:
    model_path: "/data/ref"
    hyper_params:
      temperature: 0.0

# 3. 列表嵌套字典（多模型配置）
working_agents:
  - name: qwen-72b-chat
    max_context: 128000
    use_vllm: true
  - name: baichuan-13b
    max_context: 64000
    use_vllm: false

python 读取示例：

import yaml

with open("complex_structures.yaml", "r", encoding="utf-8") as f:
    config = yaml.safe_load(f)

# 调用列表
print("精检索数：", config["retrieval_top_k"][1])  # 输出：5
print("GPU ID列表：", config["gpu_ids"])            # 输出：[0,1,2,3]

# 调用嵌套字典
actor_temp = config["project1"]["actor"]["hyper_params"]["temperature"]
print("Actor模型温度：", actor_temp)  # 输出：0.1

# 遍历列表字典（多模型配置）
for agent in config["working_agents"]:
    print(f"模型名：{agent['name']}，最大上下文：{agent['max_context']}")
# 输出：
# 模型名：qwen-72b-chat，最大上下文：128000
# 模型名：baichuan-13b，最大上下文：64000

高级特性（复用/锚点）：

YAML 支持锚点和引用，使用&完成锚点定义，*完成锚点引用，减少重复配置

创建 advanced_features.yaml:

# 1. 基础锚点：复用单个值
&default_temp 0.1  # 定义锚点
actor_temp: *default_temp  # 引用锚点
ref_temp: *default_temp    # 复用

# 2. 字典锚点：复用整个字典（<<: *锚点 表示继承）
&common_model_config  # 定义通用配置锚点
  device: cuda
  batch_size: 8
  temperature: 0.1

actor:
  <<: *common_model_config  # 继承通用配置
  model_path: "/data/actor"
  temperature: 0.2  # 覆盖通用配置

ref:
  <<: *common_model_config  # 复用通用配置
  model_path: "/data/ref"

# 3. 合并锚点：多个锚点合并
&base_reward
  answer_weight: 0.7
&rank_reward
  rank_weight: 0.3

total_reward:
  <<: [*base_reward, *rank_reward]  # 合并两个锚点
  baseline: 0.2  # 新增参数

<<: *common_model_config 会将通用配置的所有键值对「复制」到 actor 字典中；
如果 actor 中定义了同名键（如 temperature），则用新值覆盖复制来的原值；
未定义的键（如 device）则保留通用配置的值。