--- title: The_YAML_AI_Blueprint tags: #yaml author: [Yukiko](https://docswell.com/user/yukiko_it) site: [Docswell](https://www.docswell.com/) thumbnail: https://bcdn.docswell.com/page/57GL4XYXEL.jpg?width=480 description: The_YAML_AI_Blueprint by Yukiko published: July 02, 26 canonical: https://docswell.com/s/yukiko_it/5E1136-2026-07-02-200437 --- # Page. 1 ![Page Image](https://bcdn.docswell.com/page/57GL4XYXEL.jpg) YAML完全ガイド ——動画・画像生成AIを制御する「最強の構造化プロンプト」 原理原則から実践パイプライン、セキュリティまでを網羅するエンジニアの設計図 うさうさ研修工房 | 面白きこともなき世を面白く # Page. 2 ![Page Image](https://bcdn.docswell.com/page/4EQYG8M5JP.jpg) 結論: 人間に読みやすいデータ直列化言語 根拠: 3つのシンプルなデータ構造のみで構成され、インデントで階層を表現する 事実・データ: YAML 1.2.2公式仕様 (yaml.org) に準拠。Unicode文字集合を前提とし、JSONの上位互換として設計 「設定ファイルからAIへの指示書まで、あらゆる用途の基盤になります🐰」 # Page. 3 ![Page Image](https://bcdn.docswell.com/page/KJ4W52VV71.jpg) 全てを表現する「3つのデータ構造」 1. スカラー (Scalar): 単一の値 (文字列・数値・真偽値) key: value 2. シーケンス (Sequence): 順序付きのリスト (配列) - 要素1 - 要素2 3. マッピング (Mapping): キーと値のペアの集合 (連想配列) parent: child_key: value この「3つしかない」というシンプルさが、人間と機械の両方に優しい理由。 # Page. 4 ![Page Image](https://bcdn.docswell.com/page/LE1YWM347G.jpg) 基本構文：インデントが階層を作る インデント（半角スペース） 1 course: 2 title: LPIC-1 対策講座 4 instructor: うさうさ先生 5 modules: 6 - name: Linuxキホン 7 hours: 8 インデント（半角スペース） 階層の深さ Rule 01: タブ文字は絶対禁止 階層は必ず半角スペースで表現する。 Rule 02: コロン直後のスペース 「キー: 値」のコロンの後には必ず半角スペースが必須。 Rule 03: 閉じ括弧は不要 {}や[]に依存せず、インデントの深さがそのままデータのネスト構造を決める。 # Page. 5 ![Page Image](https://bcdn.docswell.com/page/GEWG63PZJ2.jpg) 比較研究：適材適所のデータフォーマット戦略 観点 | YAML | JSON | XML 可読性 (人手編集) | ◎ | ◯ | △ データサイズ | ◯ | ◎ | △ コメント記述 | ◎ | × | ◯ スキーマ検証 | △ | ◯ | ◎ 主な用途 | 設定ファイル・AIプロンプト | API通信 | 厳格な業務データ Evidence Box KTH（スウェーデン王立工科大学）およびSumarayらの査読付き比較研究により、実務上の適材適所が裏付けられている。 # Page. 6 ![Page Image](https://bcdn.docswell.com/page/47ZLYVKLJ3.jpg) なぜ生成AI (LLM) はYAMLを好むのか？ Human Creator -> YAML (構造化プロンプト) -> AI Model トークン効率の最適化: 括弧 {} やカンマ, が不要なため、JSONと比較して消費トークン数を抑えられ、AIの処理コストが下がる。 自然言語との親和性: インデントによる階層表現は、人間の思考プロセスや自然言語の文脈と構造が近いため、LLMが意図を誤解しにくい。 構文エラーの回避: LLMがよく起こす「JSONの閉じ括弧忘れ」という致命的なパースエラーが構造上発生しない。 # Page. 7 ![Page Image](https://bcdn.docswell.com/page/YJ6WD5QMJV.jpg) 発展構文①：アンカーによるDRY原則 (重複排除) 定義 (Anchor) defaults: &base timeout: 30 retry: 3 再利用 (Alias) -> prod: <<: *base host: prod.example.com 再利用 (Alias) -> scene_a: <<: *base subject: Rabbit プロンプトエンジニアリングでの利点 - & (アンカー): 値に名前をつけて定義。 - * (エイリアス) / <<: 定義した値をまるごとマージして再利用。 - 共通の品質設定やネガティブプロンプトを1箇所にまとめ、全シーンに反映。修正の手間を劇的に削減。 # Page. 8 ![Page Image](https://bcdn.docswell.com/page/GJ5M3YRQJ4.jpg) 発展構文②：複数行文字列の使い分け A. 改行を保持する「|」（パイプ） notes: | 1行目です 2行目も保持されます 用途：動画の台本、字幕原稿、セリフの埋め込み。 B. 改行を畳み込む「>」（大なり） description: > 長文のプロンプトを ひと続きの文章として AIに読み込ませます 用途：長文のキャプション、ひと続きで読ませたいプロンプト指示。 用途に合わせて記号を使い分けるだけで、長文プロンプトの管理が格段に楽になります！ # Page. 9 ![Page Image](https://bcdn.docswell.com/page/9E29ZGDW7R.jpg) 実践パターンA：画像生成のプリセット管理 character: name: しろうさぎアナウンサー proportion: '1:1' colors: fur: '#FFFFFF' jacket: '#1A237E' layout: character_area: 0.25 関心の分離 (Separation of Concerns) キャラクター（造形）、カラーコード、レイアウト（スライド構図）を完全に独立したマッピングとして定義。 AI制御の安定化 一部の要素（ポーズなど）を変更しても、他のパラメータを巻き込まずAIに安定した指示出しが可能。 # Page. 10 ![Page Image](https://bcdn.docswell.com/page/D7Y4RV29EM.jpg) 実践パターンB：プロンプトのバリエーション管理 variations: style: anime: ... realistic: ... mood: happy: ... dark: ... Prompt -> Style (Anime, Realistic, Watercolor) -> Unique Combination (e.g., Anime + Happy) Prompt -> Mood (Happy, Dark) -> Unique Combination (e.g., Anime + Happy) スタイルと雰囲気（ムード）の掛け合わせを階層構造で整理。呼び出す側は「style: anime」「mood: happy」と軸を組み合わせるだけで、ゼロから指示を書く手間を完全に排除。 # Page. 11 ![Page Image](https://bcdn.docswell.com/page/VENYDM8DJ8.jpg) 実践パターンC：動画生成のストーリーボード設計 video_title: AI解説動画 scenes: - id: scene_01 duration: 5 camera: pan_right - id: scene_02 duration: 3 camera: zoom_in 「同じ形の箱を並べる」原則 配列の要素 (-) を足す・消す・動かすだけで、動画全体の構成を崩さずに時間軸とシーンの編集が完結する。 # Page. 12 ![Page Image](https://bcdn.docswell.com/page/Y79PGNK8E3.jpg) 自動化パイプライン：CI/CD連携 (GitHub Actions) 1. Trigger: on: push コードの変更を検知 2. Build: プロンプトと素材の組み立て 3. Render: AI動画・画像生成APIの実行 4. Deploy: 完成品の自動書き出し・公開 1枚の画像設定から、パイプライン全体の自動化まで、YAMLの「3つの基本構造」だけで一貫して記述できるのが最大の強み。 # Page. 13 ![Page Image](https://bcdn.docswell.com/page/G78DVKRZ7D.jpg) 防衛術：セキュリティの罠と任意コード実行 (RCE) YAMLは任意のオブジェクト型 (!!python/object等) を生成できる強力な仕様を持つため、セキュリティリスクが伴う。 config = yaml.load(data, Loader=yaml.Loader) 危険：信頼できない入力を処理すると、任意コード実行 (CVE-2022-1471等) につながる致命的な罠。 config = yaml.safe_load(data) 安全：標準的なデータ型のみを許可する安全なロード関数を既定にする。入力検証の徹底が必須。 # Page. 14 ![Page Image](https://bcdn.docswell.com/page/L7LM5ZK1JR.jpg) トラブルシューティング：初心者がハマる落とし穴 NG (落とし穴) | OK (回避策) | 理由 country: NO | country: "NO" | ノルウェー問題：真偽値 (False) として誤解釈されるのを防ぐため文字列はクォートで囲む。 time: 10:30 | time: "10:30" | コロン後のスペース忘れ：コロンの直後には半角スペースが必須。数値・時刻風の文字列もクォートする。 ブロックスタイルとフロースタイル ([]や{})の混在 | 1ファイル内で書式を統一する | パースエラーや人間の読み間違いを防ぐため、記述ルールをプロジェクトで統一する。 # Page. 15 ![Page Image](https://bcdn.docswell.com/page/4EMY3V25EW.jpg) 公式仕様 (Foundation) 適材適所 (Research) 構造化プロンプト (AI Advantage) 堅牢なセキュリティ (Guardrails) The YAML Ecosystem YAMLは単なる設定ファイルから、人間とAIを正確に繋ぐ「最強の共通言語」へと進化した。 面白きこともなき世を面白く うさうさ研修工房