AI YAML（ヤムル）入門 基礎編　基本文法を実務で使ってみよう

はじめに

AITCセンター長の深谷です。

生成AIを業務に活用しようとすると、最初にぶつかる壁は「モデルの性能」だけではありません。AIに渡すデータが、どのような形式で整理されているか？も、回答精度や再利用性を大きく左右します。

これまで、文章をAIが読み取りやすい形に整える方法として、"Markdownの基本文法"を紹介してきました。Markdownは、見出しやリストによって文章の構造を明示できるため、手順書、議事録、不具合報告、設計メモといった「人が読む文書」をAI Readyにするのに向いています。

AITC | AI TRANSFORMATION CENTER

AI Markdown入門から基礎編　基本文法を実務で使ってみよう

🕒️2026年2月24日

一方、実務でAIに扱わせたい情報は、文章だけではありません。

例えば、製造設備でアラームが発生したときには、次のような情報を扱います。

- どの設備で発生したか
- アラームコードは何か
- 重大度はどの程度か
- どの症状が出ているか
- 何を、どの順番で確認するか
- どの条件で保全部門へ連絡するか

こうした「項目」「階層」「繰り返し」「数値」「真偽値」を含む情報は、文章だけで記述するよりも、構造化データとして表した方が、人にもAIにも意味が伝わりやすくなります。

そこで有力な選択肢になるのが、YAML（ヤムル）です。

本記事では、製造設備の異常対応ルールを題材に、YAMLの基本文法を実務で使える形で説明します。YAMLを初めて見る方でも、記事を読み終えたときに「1件の異常対応ルールを、自分で構造化して書ける」ことを目指します。

なお、ここで扱う考え方は製造業に限りません。問い合わせの振り分けルール、製品仕様、テストケース、AIエージェントの設定など、項目と階層を持つ情報であれば同じように応用できます。自分の業務データに置き換えながら読み進めてください。

改めてYAML（ヤムル）とは？

YAMLは、人が読み書きしやすいことを重視したデータ記述形式です。正式名称は「YAML Ain't Markup Language」で、「YAMLはマークアップ言語ではない」です。

一言で言えば、YAMLはデータの項目と階層を、少ない記号で表せる形式です。

例えば、設備の名称と設置ラインは次のように書けます。

name: 画像検査装置
line: Line-A

`name`と`line`が項目名、その右側が値です。見た目は簡潔ですが、プログラムやAIから見ると、「設備名は画像検査装置」「設置ラインはLine-A」という関係が明示されています。

YAMLは、DockerやCI/CD、各種クラウドサービスなど、多くの設定ファイルで利用されています。生成AIの領域でも、プロンプトの構成、AIエージェントの役割、利用できるツール、評価テストケース、ガードレールなどを定義する形式としてよく使われます。

本記事では、"YAML 1.2.2"を前提に、実務で使いやすい書き方を説明したいと思います。

yaml.org

YAML Ain’t Markup Language (YAML™) revision 1.2.2

https://yaml.org/spec/1.2.2/

Markdown、JSON、YAMLはどう使い分けるのか？

Markdown、JSON、YAMLは、いずれもテキストで記述できるため、生成AIと相性のよい形式です。ただし、得意なことは異なります。

例えば、設備停止時の背景や注意事項を詳しく説明するならMarkdownが向いています。一方、「重大度がhighなら停止する」「15分以内に復旧しなければ保全へ連絡する」といった条件を項目として明示するならYAMLが向いています。

整理すると、次のように考えると分かりやすいと思います。

> Markdownは「人が読む説明や手順」を構造化する。  

> YAMLは「AIやシステムも利用する項目やルール」を構造化する。

もちろん、どちらか一方だけを選ぶ必要はありません。MarkdownのSOPからYAMLの異常対応ルールを生成したり、YAMLから人向けのチェックリストを作ったりすることもできます。文章とデータを役割分担させることが重要です。

製造設備の異常対応ルールを題材に、文法を“現場データの形”で覚える

YAMLの文法も、記号だけを個別に覚えるより、実際に使うデータの型を前提にした方が理解しやすくなります。

そこで今回は、Line-Aに設置された画像検査装置`Vision-02`で、アラーム`E231`が発生した場合の異常対応ルールを作ります。

まずは、「最低限この形にしておけば、人が読みやすく、AIも項目を取り違えにくい」というテンプレートを定義します。以降の章では、このテンプレートを分解しながらYAMLの基本文法を説明していきます。

すぐ使える異常対応ルールのテンプレート

# 製造設備の異常対応ルール
equipment:
  id: Vision-02
  name: 画像検査装置
  line: Line-A
  enabled: true
alarm:
  code: E231
  severity: high
  automatic_stop: true
symptoms:
  - 画像を取得できない
  - 判定結果が連続してNGになる
checks:
  - order: 1
    item: カメラ接続
    expected: connected
  - order: 2
    item: 装置温度
    threshold:
      operator: "<="
      value: 70.0
      unit: "°C"
response: |
  装置を安全停止する。
  カメラケーブルと電源状態を確認する。
  復旧しない場合は保全部門へ連絡する。
remarks: >
  作業を開始する前に、
  必ず設備の安全状態を確認してください。
escalation:
  required: true
  contact: 設備保全部門
  timeout_minutes: 15
  secondary_contact: null

最初は少し複雑に見えるかもしれません。しかし、使っている基本要素は、大きく分けると次の3つです。

- Mapping（マッピング）：キーと値の組み合わせ
- Sequence（シーケンス）：複数項目の並び
- Scalar（スカラー）：文字列、数値、Booleanなどの単一の値

この3つと、階層を表すインデントを理解すれば、YAMLの基本的な読み書きはできるようになります。

Mapping：キーと値で情報の意味を固定する

YAMLで最も基本となるのがMappingです。日本語では「対応付け」と考えると分かりやすく、`キー: 値`の形で書きます。

id: Vision-02
name: 画像検査装置
line: Line-A

この例では、`id`、`name`、`line`がキーです。それぞれに、`Vision-02`、`画像検査装置`、`Line-A`という値が対応しています。

あと、注意点としては、コロン`:`の後には、半角スペースを1つ入れることです。

# 正しい
name: 画像検査装置
# 間違い
name:画像検査装置

人が文章で「Line-Aの画像検査装置Vision-02」と書けば意味は分かります。しかし、AIがそこから設備ID、設備種別、ライン名を毎回正しく理解できるとは限りません。

Mappingで項目名を固定すると、AIに「`equipment.id`を答えてください」「`alarm.severity`がhighのルールだけ抽出してください」と指示できるようになります。情報の意味を文章の読み取りに委ねず、キーによって明示することが、YAMLをAI Ready Dataとして使う第一歩です。

キーの名前は、短さより一貫性を優先する

実務では、キーの名前が人によって揺れることがあります。

# 表記が揺れている例
equipment_id: Vision-02
machine_no: Vision-03
device: Vision-04

同じ意味の項目に異なるキーを使うと、AIやプログラムが一括処理しにくくなります。`equipment_id`なら`equipment_id`に統一するなど、組織内で命名ルールを揃えましょう。

私は、キーには英小文字とアンダースコアを使い、値には現場で使う日本語を入れる形が扱いやすいと思います。

secondary_contact: 設備保全部門
timeout_minutes: 15

`timeout`だけでは単位が分かりませんが、`timeout_minutes`なら15分であることが明確です。AIにとっても人にとっても、単位や意味をキーに含めることをおすすめします。

インデント：空白で情報の階層を表す

YAMLでは、行頭のインデントによって情報の親子関係を表します。

equipment:
  id: Vision-02
  name: 画像検査装置
  line: Line-A

`id`、`name`、`line`は2文字分インデントされているため、すべて`equipment`の下位項目です。

この構造は、次のように読めます。

- equipment
  - idはVision-02
  - nameは画像検査装置
  - lineはLine-A

つまり、YAMLでは空白が見た目を整えるための飾りではなく、データの意味そのものです。

インデントは半角スペース2つで統一する

YAMLでは、親より深い階層を1文字以上インデントすれば表現できますが、実務では半角スペース2つに統一するのがおすすめです。

また、インデントにタブは使えません。エディターの設定によってTabキーがスペースへ変換される場合は問題ありませんが、YAMLファイル内にタブ文字を直接入れないようにしてください。

インデントがないと、親子関係が変わってしまう

次の例は見た目が似ていますが、意味が異なります。

equipment:
id: Vision-02
name: 画像検査装置

この書き方では、`id`と`name`は`equipment`の子ではありません。`equipment`は値を持たない`null`として解釈され、`id`と`name`は同じ最上位階層の項目になります。

インデントが1段ずれるだけで、「どの設備の情報か」「どの確認項目の判定基準か」が変わります。人が見落としやすく、AIも誤った構造をそのまま受け取ってしまいます。

YAMLを書くときは、同じ階層のインデントを必ず揃えましょう。

Sequence：複数の症状や確認項目をリストにする

同じ種類の項目を複数並べるときは、Sequenceを使います。各要素の先頭にハイフンと半角スペース`- `を付けます。

symptoms:
  - 画像を取得できない
  - 判定結果が連続してNGになる

この例では、`symptoms`に2つの症状が登録されています。

文章で「画像を取得できない、または判定結果が連続してNGになる」と書くこともできます。しかし、リストにしておけば、AIは症状が2件あると認識しやすく、1件ずつ抽出・比較・追加することができます。

Sequenceの中にMappingを入れる

Sequenceには、単純な文字列だけでなく、複数の項目を持つMappingも並べられます。

checks:
  - order: 1
    item: カメラ接続
    expected: connected
  - order: 2
    item: 装置温度
    expected: 70°C以下

ここでは、確認作業が2件あります。それぞれの作業に`order`、`item`、`expected`という項目を持たせています。大事なのは、2行目以降の位置です。

  - order: 1
    item: カメラ接続
    expected: connected

`item`と`expected`を`order`と同じMappingに含めるため、ハイフンの後に始まった`order`のキー位置に揃えます。

この形にすると、AIは「確認順序」「確認対象」「正常条件」を1件の確認作業としてまとめて扱えます。例えば、確認項目だけをチェックリストとして出力したり、`order`順に案内したりすることが容易になります。

MappingとSequenceのネスト：判定条件をひとまとまりにする

YAMLでは、MappingとSequenceを組み合わせて階層を深くできます。これをネスト、または入れ子と呼びます。

例えば、装置温度の判定条件を、演算子、値、単位に分けてみます。

checks:
  - order: 2
    item: 装置温度
    threshold:
      operator: "<="
      value: 70.0
      unit: "°C"

このデータは、次の構造になっています。

- `checks`は確認作業のリスト
- リストの要素は`order`、`item`、`threshold`を持つ
- `threshold`は、さらに`operator`、`value`、`unit`を持つ

`expected: 70°C以下`と1つの文字列で書くより、`operator`、`value`、`unit`に分けた方が、AIやプログラムが条件を正確に利用できます。

例えば、単位が°Cの項目だけを集める、閾値が70を超えるルールを検査する、自然言語で「70°C以下」と説明し直す、といった処理がしやすくなります。

ただし、階層は深ければ深いほどよいわけではありません。細かく分けすぎると、人が編集しにくくなります。検索・比較・判定に使いたい単位で項目を分けるのがポイントです。

Scalar：文字列、数値、Boolean、nullを使い分ける

Mappingの値やSequenceの各要素として置かれる、単一の値をScalarと呼びます。

基礎編で押さえたい主なScalarは、次の4種類です。

数値は単位と分ける

threshold:
  value: 70.0
  unit: "°C"

`70.0°C`を1つの文字列にすると、そのままでは数値比較ができません。値と単位を分ければ、`value`を数値として比較し、`unit`で意味を確認できます。

製造業では、温度、圧力、時間、回転数、公差など、数値と単位の組み合わせが頻繁に登場します。AIに計算や条件判定をさせる可能性があるなら、値と単位を別項目にするのがおすすめです。

Booleanは「はい／いいえ」の状態に使う

enabled: true
automatic_stop: true
required: true

Booleanは、`true`または`false`の2値を表します。「有効か」「停止が必要か」「承認済みか」といった状態に向いています。

一方で、`yes`、`no`、`on`、`off`は、YAMLのバージョンやパーサーによって解釈が揺れることがありますので、Booleanは`true`と`false`に統一するのが良いと言われています。

nullは「未設定」を明示する

secondary_contact: null

`null`は、項目そのものは存在するが、値がまだ設定されていないことを表します。

キーを書かない場合と、`null`を書く場合は意味が異なります。キーがなければ「その項目を扱っていない」、`null`なら「項目はあるが、現時点では未設定」と区別できます。

AIに不足情報を確認させたい場合も、`null`は便利です。例えば、「値が`null`の項目だけを抽出し、担当者に確認する質問を作ってください」と指示できるわけです。

コメントと空行：人向けの補足を残す

YAMLでは、`#`から行末までがコメントになります。コメントはデータとして読み込まれませんが、編集する人への説明を残せます。

# 画像検査装置の異常対応ルール
alarm:
  code: E231  # HMIに表示されるアラームコード
  severity: high

コメントは、値の根拠、編集時の注意、暫定対応であることなどを残すのに向いています。ただし、AIやシステムが必ず利用すべき情報をコメントだけに書いてはいけません。

# 避けたい例：重要条件がコメントにしかない
automatic_stop: true  # 人が安全を確認してから実行すること

「人の安全確認が必要」という条件をAIにも確実に扱わせたいなら、正式なキーとして記述します。

automatic_stop: true
human_safety_check_required: true

コメントは人向けの補足、キーと値はデータとして利用する情報、と役割を分けましょう。また、空行はデータの意味を変えません。設備、アラーム、症状、確認項目などのまとまりの間に空行を入れると、人が読みやすくなります。

プレーン文字列とクォート：値を意図どおりに守る

YAMLでは、多くの文字列をクォートなしで書けます。これをプレーン文字列と呼びます。

name: 画像検査装置
severity: high
contact: 設備保全部門

簡潔で読みやすいため、特別な理由がなければプレーン文字列で問題ありません。

ただし、文字列の内容がYAMLの記号やデータ型と紛らわしい場合は、シングルクォート`'...'`またはダブルクォート`"..."`で囲みます。

文字列として保持したい値はクォートする

part_number: "00123"
display_text: "true"
label: "#A-102"
operator: "<="

`00123`を数値として解釈すると、先頭のゼロを保持できない実装があります。`true`はBoolean、`#`はコメントの開始と解釈される可能性があります。「見たままの文字列」として守りたい値は、クォートしておくと意図が明確です。

設備ID、品番、郵便番号、日付のような値も、計算に使わない識別子であれば文字列として扱う方が安全な場合があります。

シングルクォート：文字をほぼそのまま保持する

message: '装置名は「Vision-02」です'
path: 'C:\logs\vision'

シングルクォート内では、バックスラッシュ`\`をエスケープ記号として扱いません。Windowsのパスや正規表現など、バックスラッシュをそのまま残したい値に向いています。

シングルクォート自体を含めたい場合は、2つ重ねます。

message: '保全員の回答は ''確認中'' です'

ダブルクォート：エスケープを使う

ダブルクォート内では、`\n`を改行、`\t`をタブとして扱うなど、エスケープシーケンスを利用できます。ダブルクォートそのものは`\"`、バックスラッシュは`\\`と書きます。

message: "画面に\"E231\"と表示された"
path: "C:\\logs\\vision"

実務では、通常の日本語はプレーン文字列、記号を確実に文字として扱いたい場合はクォート、エスケープが必要な場合はダブルクォート、と使い分けると分かりやすいです。

複数行文字列`|`：手順の改行をそのまま残す

異常対応の手順や注意事項は、複数行で書きたくなります。改行を保持したいときは、Literal Block Scalarと呼ばれる`|`を使います。

response: |
  装置を安全停止する。
  カメラケーブルと電源状態を確認する。
  復旧しない場合は保全部門へ連絡する。

この値は、改行を含む文字列として扱われます。

手順、ログ、SQL、プロンプトなど、行の区切り自体に意味がある情報に向いています。

AIに異常対応を案内させる場合も、1行ずつ改行されていれば、手順の順序を保った回答を作りやすくなります。ただし、本当に順序や各工程をデータとして個別に扱いたいなら、文章を`|`にまとめるより、`checks`のようなSequenceとして記述する方が適切です。

`|`は「複数行の文章を保持する」、Sequenceは「複数のデータ項目を分けて扱う」と覚えてください。

複数行文字列`>`：長い説明を1つの文章として扱う

改行位置を保持せず、複数行を1つの文章として扱いたいときは、Folded Block Scalarと呼ばれる`>`を使います。

remarks: >
  作業を開始する前に、
  必ず設備の安全状態を確認してください。

この値は、行の折り返しがスペースへ変換された文字列として扱われます。説明文が長く、YAMLファイル上では読みやすい位置で折り返したいものの、データとしては1つの段落にしたい場合に向いています。

どう使い分けるの？と思われた方もいらっしゃると思いますので、使い分けを比較します。

改行を残すなら`|`、1つの文章に畳むなら`>`と覚えれば十分です。

完成版：異常対応ルールをAIが扱える形にする

ここまでの文法を組み合わせると、冒頭の異常対応ルールが完成します。

# 製造設備の異常対応ルール
equipment:
  id: Vision-02
  name: 画像検査装置
  line: Line-A
  enabled: true
alarm:
  code: E231
  severity: high
  automatic_stop: true
symptoms:
  - 画像を取得できない
  - 判定結果が連続してNGになる
checks:
  - order: 1
    item: カメラ接続
    expected: connected
  - order: 2
    item: 装置温度
    threshold:
      operator: "<="
      value: 70.0
      unit: "°C"
response: |
  装置を安全停止する。
  カメラケーブルと電源状態を確認する。
  復旧しない場合は保全部門へ連絡する。
remarks: >
  作業を開始する前に、
  必ず設備の安全状態を確認してください。
escalation:
  required: true
  contact: 設備保全部門
  timeout_minutes: 15
  secondary_contact: null

このYAMLには、次の情報が明示されています。

- 対象設備は`Vision-02`
- アラームコードは`E231`
- 重大度は`high`
- 自動停止の対象である
- 症状は2件ある
- 確認作業には順序と判定条件がある
- 15分以内に復旧しない場合の連絡先がある
- 二次連絡先は未設定である

自然文の手順書から同じ情報を読み取る場合、AIは文章を解釈し、項目を推測して抜き出す必要があります。YAMLなら、設備、アラーム、症状、確認、対応、エスカレーションが最初から分かれています。

これにより、例えば次のようなAI活用へ展開できます。
- アラームコードから該当ルールを検索する
- 確認項目を順番に案内する
- 未設定の項目を抽出し、担当者への質問を作る
- 過去の不具合報告からYAMLの下書きを生成する
- YAMLから人向けのSOPやチェックリストを生成する
- 複数ルールの重大度、閾値、連絡条件を比較する

AIにYAMLを書かせるときの3つの注意点

作成を生成AIはYAMLに任せたいときも多いでしょう。AIにYAMLを書かせるときは、特に次の3点は押さえておきましょう。

1. キーの一覧と意味を先に指定する

AIに「異常対応ルールをYAMLにしてください」とだけ指示すると、実行のたびに`machine`、`equipment`、`device`など、キーが変わることがあります。

利用するキー、必須項目、単位、値の候補を先に指定しましょう。

【プロンプト例】
次のキー構成を変更せず、異常対応ルールをYAMLで出力してください。
equipment: id, name, line
alarm: code, severity, automatic_stop
symptoms: 文字列のリスト
checks: order, item, expected
escalation: required, contact, timeout_minutes

2. YAML以外の説明を混ぜないようにする

プログラムで読み込む場合は、「以下がYAMLです」といった説明文が混ざるとエラーになることがありますので、出力条件を明示します。

【プロンプト例】
回答にはYAMLのみを出力し、前後に説明文やMarkdownのコードフェンスを付けないでください。

3. 生成後に必ず構文と内容を確認する

インデントのずれ、キーの重複、数値と文字列の取り違え、必須項目の欠落がないかを確認してください。

AIが生成したYAMLを、すぐに設備制御や業務システムへ渡すのは危険です。まずYAMLパーサーで正しく読み込めることを確認し、次に業務ルールとして正しいかを人がレビューします。

YAMLとして正しくても、業務上正しいとは限りません。「構文の検証」と「内容の検証」は別物です。

まとめ

本記事で説明した内容を、表形式でまとめます。

Mappingで項目の意味を固定し、インデントで親子関係を表し、Sequenceで繰り返しを分け、Scalarの型を意識する。長い手順や説明は`|`と`>`で整理する。これだけでも、異常対応ルールを、人とAIが同じ構造で理解できるデータへ近づけられます。

まずは、既存の異常対応手順や問い合わせルールを1件選び、項目名を決めてYAMLに書き直してみてください。文章の中に埋もれていた設備、条件、閾値、連絡先が、明確な構造として見えてくると思います。

生成AI活用の成否は、モデル性能だけでは決まりません。現場にある情報資産が、AIにとって読み取りやすく、比較しやすく、検証しやすい形になっているか？に、大きく左右されます。

AI Ready Dataの整備から、RAG、AIエージェント、業務システムとの連携まで、本気で生成AIを業務に活用したいと考えていらっしゃる方は、ぜひ電通総研にご相談ください。

次回：AI YAML入門 応用編　再利用・検証・安全な運用を学ぼう

次回の応用編では、同じ異常対応事例を使って、今回説明しなかった以下の内容を説明したいと思います。

アンカー`&`とエイリアス`*`による共通ルールの再利用、`---`を使った複数ドキュメント、`|-`や`>+`による末尾改行の制御、YAML 1.1と1.2の違い、パーサーによる解釈差など。

筆者
AITC センター長
深谷 勇次