为什么大模型配置文件越来越爱用 YAML：和 JSON 对比，一次讲清核心语法与适用场景

低调小一

393人浏览 · 2026-04-30 17:49:07

低调小一 · 2026-04-30 17:49:07 发布

为什么大模型配置文件越来越爱用 YAML：和 JSON 对比，一次讲清核心语法与适用场景

受众假设：已经理解 JSON 和基本编程概念的工程师。

本文聚焦：为什么 AI 时代大量配置文件偏向 YAML，它和 JSON 在语法、可读性和适用场景上到底差在哪。

摘要（先看结论）

YAML 和 JSON 本质上都在描述树形数据，但它们优化的目标不同：JSON 更偏“机器交换”，YAML 更偏“人类编辑”。
在大模型和 Agent 场景里，配置文件常常要同时承载 模型参数、工具列表、工作流节点、多行 prompt，这正是 YAML 的强项。
YAML 的核心语法并不复杂，工程上最常用的无非是 对象、数组、字符串、多行字符串、注释 这几类。
真正容易踩坑的地方不是“功能不够”，而是 缩进、引号、多行文本 和“看起来像字符串、其实会被解析成别的类型”。
一句话总结：配置文件 往往更适合 YAML，接口请求和数据交换 依然更适合 JSON。

1. 关键概念

先把一句最重要的话说清楚：

YAML 不是“更高级的 JSON”，它更像是“更适合人读和人改的配置表达方式”。

JSON 的优点你已经很熟悉了：结构清晰、规则统一、解析器几乎到处都有、非常适合接口请求和程序之间交换数据。

YAML 的出场点不太一样。它最擅长的场景是：

文件要被人长期维护
层级结构比较深
需要写注释
需要放多行文本
经常要在代码评审里阅读差异

这正好解释了为什么在 AI 时代，YAML 的存在感越来越强。

一个典型的大模型配置文件，往往不只是几组键值对，而是会同时包含这些内容：

模型提供商与模型名
采样参数，例如 temperature
系统提示词和角色设定
工具列表
工作流节点或任务编排

如果这些东西全部塞进 JSON，程序当然能读，但人会读得很累。尤其一旦出现多行 prompt，可维护性会明显变差。

先看一个最小例子。下面这段配置，表达的是同一件事。

{
  "provider": "openai-compatible",
  "model": "deepseek-chat",
  "temperature": 0.2,
  "tools": ["web_search", "calculator"],
  "system_prompt": "你是一个严谨的技术作者。\n先给结论，再给解释。\n不要使用营销化表达。"
}

provider: openai-compatible
model: deepseek-chat
temperature: 0.2
tools:
  - web_search
  - calculator
system_prompt: |-
  你是一个严谨的技术作者。
  先给结论，再给解释。
  不要使用营销化表达。

程序眼里，这两段配置都能变成同一种内存结构。差别主要在于：第二种更像是给工程师看的。

2. 核心语法

2.1 对象和数组：大括号变少了，缩进变重要了

很多人第一次看 YAML，容易形成一个误解：

YAML 靠缩进表达一切。

这其实不对。

更准确的说法应该是：

对象 主要靠 key: value 加缩进表达层级
数组 主要靠 - 标记每一个元素，再配合缩进表达层级

所以 YAML 不是“只靠空格”，而是三样东西一起工作：

冒号 表示键值对
缩进 表示谁属于谁
短横线 表示这是数组里的一个元素

+------------------+----------------------+------------------------------+
| 结构类型         | JSON 主要靠什么      | YAML 主要靠什么             |
+------------------+----------------------+------------------------------+
| 对象 object      | {} 和 "key": value   | key: value + 缩进           |
| 数组 array       | [] 和逗号分隔        | - + 缩进                    |
+------------------+----------------------+------------------------------+

先看对象。

在 JSON 里，一个对象通常长这样：

{
  "model": "deepseek-chat",
  "temperature": 0.2
}

到了 YAML 里，同样的对象更像这样：

model: deepseek-chat
temperature: 0.2

这里最关键的是：

model: 和 temperature: 都是键
冒号后面跟的是值
如果值本身还是一个对象，就继续向下缩进

再看数组。

在 JSON 里，数组靠 [] 包起来：

{
  "tools": ["search", "calc"]
}

到了 YAML 里，数组不靠 []，而是靠每一行前面的 -：

tools:
  - search
  - calc

这里的 - 不能省。它的意思不是装饰，也不是普通分隔符，而是在明确告诉解析器：

下面这一项是数组里的一个元素。

如果数组里的每个元素本身又是对象，就会写成这样：

tools:
  - name: search
    type: builtin
  - name: calc
    type: builtin

这时候的阅读方式应该是：

tools: 表示这里有一个字段
这个字段的值不是单个对象，而是一个数组
每个 - 开头的块，都是数组里的一个对象

所以这一节最容易记错的点，其实不是缩进，而是：

缩进 只负责表达层级
- 才负责表达“这是数组项”

工程上先记住三条就够了：

缩进只用空格，不要用 Tab
同一层级的缩进必须对齐
键和值之间是 冒号 + 空格

例如下面就是一个常见的 AI 工作流配置：

workflow:
  name: article-review
  steps:
    - name: summarize
      model: deepseek-chat
    - name: verify
      model: gpt-4.1

如果把同样的结构写成 JSON，通常会长这样：

{
  "workflow": {
    "name": "article-review",
    "steps": [
      {
        "name": "summarize",
        "model": "deepseek-chat"
      },
      {
        "name": "verify",
        "model": "gpt-4.1"
      }
    ]
  }
}

如果你把 steps 下面某一行多缩进或少缩进两个空格，解析器看到的结构就可能完全不是你以为的样子。

2.2 字符串：YAML 更宽松，但也更容易“看起来没问题”

JSON 很严格，字符串必须写在双引号里。YAML 更宽松，很多时候可以直接裸写：

provider: openai-compatible
model: deepseek-chat

这确实省事，但代价是：有些内容你以为是普通字符串，解析器未必也这么想。

工程上最稳妥的经验是：

普通短字符串，裸写可以接受
含特殊符号的字符串，优先加引号
像布尔值、空值、数字这种“容易被误判”的内容，宁可显式写清楚

例如这两种写法，程序可能会得到不同的结果：

enabled: false

enabled: "false"

第一种通常会被解析成布尔值，第二种才是字符串。

所以 YAML 的问题从来不是“表达不了”，而是“省略写法太多时，人容易误判类型”。

2.3 多行文本：这是 YAML 在 AI 配置里最有价值的地方

如果只说一个 YAML 比 JSON 更适合 AI 配置的原因，我会选 多行字符串。

因为很多 AI 配置文件里最不适合写成单行的内容，就是 prompt。

先看 JSON：

{
  "system_prompt": "你是一个技术科普作者。\n你的回答要先讲结论。\n然后再补原理。\n避免空洞套话。"
}

再看 YAML：

system_prompt: |-
  你是一个技术科普作者。
  你的回答要先讲结论。
  然后再补原理。
  避免空洞套话。

后者的好处非常直接：

读的时候就是最终文本的样子
改一行 prompt 不需要数转义字符
代码评审时更容易看出改动点

你可以把它理解成：

人工编辑配置
-> 希望看到“文本本来的样子”
-> prompt 往往天然是多行内容
-> YAML 比 JSON 更顺手

顺带记一个最常用的规则：

| 表示保留换行
>- 这类写法通常用于把多行折叠成更平滑的文本

日常写 AI 配置时，最常见、也最不容易出错的就是 | 或 |-。

2.4 注释：配置文件给人看的证据之一

JSON 原生不支持注释，这件事在“数据交换”场景里没问题，但在“长期维护配置”场景里经常让人难受。

YAML 则天然支持注释：

provider: openai-compatible
model: deepseek-chat

# 控制输出更稳定，适合摘要和提炼任务
temperature: 0.2

这一点看似不起眼，但在团队协作里很有价值。因为很多配置并不是“写一次永远不动”，而是会随着模型、工具链和任务场景不断调整。

3. 为什么 AI 配置场景更偏 YAML

现在把语法差异放回工程现实里看，就更容易理解了。

+------------------+     +------------------+     +----------------------+
| 工程师编辑配置    | --> | YAML 解析成对象   | --> | 程序运行时发 JSON 请求 |
+------------------+     +------------------+     +----------------------+
         |                        |                            |
         | 人类可读               | 内部结构统一               | 机器交换友好
         | 可写注释               |                            |
         | 适合多行 prompt        |                            |

这张图说明了一个经常被忽略的事实：

很多系统并不是“YAML 取代了 JSON”，而是“人写 YAML，程序内部处理后，再对外发 JSON”。

也就是说，它们根本不是非此即彼的关系，而是处在不同层面：

YAML 解决的是“配置文件怎么写更容易维护”
JSON 解决的是“程序之间怎么交换数据更简单”

放到 AI 场景里，YAML 更受欢迎通常有四个原因：

层级多：模型、工具、路由、节点、参数往往天然是嵌套结构
文本重：系统提示词、角色定义、模板文本经常是多行
需要注释：同一个参数为什么这么配，往往需要留给后来者解释
评审频繁：配置变更通常会进入代码评审，可读性直接影响维护成本

但这不意味着 JSON 过时了。

如果你在做下面这些事情，JSON 往往仍然是更自然的选择：

调模型接口
存接口响应
做日志事件上报
在不同服务之间传输结构化数据

所以更准确的判断不是“谁更先进”，而是“这份内容主要是给谁看的”。

如果主要给程序看，JSON 很好。

如果主要给人维护，再交给程序解析，YAML 往往更合适。

4. 常见误区

误区一：YAML 就是少写几个括号的 JSON。不完全是。两者能表达的主干数据结构很接近，但 YAML 额外强调可读性，也带来了更多省略写法和更多解析细节。
误区二：YAML 更适合所有场景。不是。接口请求、日志、服务间通信，通常还是 JSON 更稳定、更统一。
误区三：YAML 既然灵活，那就尽量少写引号。灵活不等于随意。能被误解成布尔值、数字或空值的内容，最好显式写清楚。
误区四：高级特性越多越高级。锚点、多文档这些能力确实存在，但如果团队里多数人并不熟，过度使用只会降低可读性。
误区五：YAML 容易读，所以不容易出错。恰恰相反。它最常见的错误通常都很朴素：缩进不对、层级错位、字符串类型判断错误。