ChatML 文檔大更新：從標記語言到實務範例

近期，OpenAI 正式發布了最新的 ChatML 文檔更新，旨在進一步標準化對話格式化，並提升開發者在多平台會話式應用中的可擴展性。對於 WordPress、Flutter 或 AWS Kiro 等環境下嵌入 AI 聊天功能的開發者而言，了解此更新的核心變更與實務落地方式，將能有效降低開發成本並避免兼容性風險。

1. ChatML 的核心概念與新語法

角色（Role）：從系統（system）、用戶（user）到助手（assistant），透過 role 標籤進行明確標記。
訊息（Message）：以 content 欄位傳遞純文本或 JSON 結構，支援 Markdown、HTML 或圖片附件。
上下文維持（Contextual Context）：新增 ref_id 與 response_needed 參數，可在多輪對話中保持訊息關聯，並主動請求回應。

下列範例展示如何在一個簡短對話中結合前述語法：

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "請提供最新的 Flutter 3.38 更新內容。"
    },
    {
      "role": "assistant",
      "content": "Flutter 3.38 主要更新包含 iOS 26 與 Android 15 的原生支援，以及 16KB 記憶體分頁優化。此版本特別優化了 UIScene 的一致行為，確保在多任務環境下仍能順暢切換。"
    }
  ],
  "model": "gpt-4o-mini",
  "response_needed": true
}

2. WordPress 與 ASP.NET 環境下的實踐技巧

在 WordPress 上嵌入 ChatML 對話功能，可利用 WP REST API 與 External PHP 腳本協同。以下展示一段實作結構：

<?php
function get_chatml_response( $user_query ) {
    $payload = [
        "messages" => [
            [
                "role" => "system",
                "content" => "You are a WordPress support bot."
            ],
            [
                "role" => "user",
                "content" => $user_query
            ]
        ],
        "model" => "gpt-4o-mini"
    ];

    $response = wp_remote_post( 'https://api.openai.com/v1/chat/completions', [
        'headers' => [
            'Authorization' => 'Bearer ' . get_option( 'openai_api_key' ),
            'Content-Type'  => 'application/json',
        ],
        'body' => wp_json_encode( $payload )
    ]);

    $body = wp_remote_retrieve_body( $response );
    return json_decode( $body, true );
}
?>

上述函式可直接呼叫於任何 Gutenberg 區塊或短碼中，使用者發送訊息後即得到即時回應。若想進一步提升安全性，可在後端啟用 filter('allowed_html', '__return_empty_array'); 限制輸入內容，避免 XSS 攻擊。這種做法亦呼應今年 AWS Kiro 更新所說的「提升 AI 開發可靠度」與「CLI 與規格正確性測試」的方向。

3. 與 Flutter 3.38 之對應實務

Flutter 3.38 的 UIScene 與 Android 15 特性可直接用於構建聊天 UI，讓 WordPress 可透過 FlutterWeb 或 WebView 內嵌對話介面。進一步結合 ChatML 的 markdown 解析能夠呈現專業風格的回覆，並透過 16KB 記憶體分頁減少欄位渲染延遲。以下示範 Flutter 的簡易程式碼片段：

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';

class ChatScreen extends StatefulWidget {
  @override
  _ChatScreenState createState() => _ChatScreenState();
}

class _ChatScreenState extends State {
  final TextEditingController _controller = TextEditingController();
  List<Map<String, dynamic>> _messages = [];

  Future _sendMessage(String text) async {
    final payload = {
      "messages": [
        {"role": "user", "content": text}
      ],
      "model": "gpt-4o-mini"
    };
    final response = await http.post(
      Uri.parse('https://api.openai.com/v1/chat/completions'),
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: jsonEncode(payload),
    );
    final data = jsonDecode(response.body);
    setState(() {
      _messages.add({"role": "assistant", "content": data['choices'][0]['message']['content']});
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('ChatML Demo')),
      body: Column(
        children: [
          Expanded(
            child: ListView.builder(
              itemCount: _messages.length,
              itemBuilder: (_, i) {
                final m = _messages[i];
                return ListTile(
                  title: Text(m['role']),
                  subtitle: Text(m['content']),
                );
              },
            ),
          ),
          Padding(
            padding: EdgeInsets.all(8),
            child: TextField(
              controller: _controller,
              onSubmitted: (value) {
                _sendMessage(value);
                _controller.clear();
              },
              decoration: InputDecoration(
                  hintText: '輸入訊息',
                  suffixIcon: IconButton(
                    icon: Icon(Icons.send),
                    onPressed: () {
                      _sendMessage(_controller.text);
                      _controller.clear();
                    },
                  )),
            ),
          ),
        ],
      ),
    );
  }
}

4. 重要的兼容性注意事項

不要將舊的 role: system 語法直接轉譯為 role: system_ref；正確做法是保留 role: system 並使用 content 字段。
對於歷史紀錄存儲，建議在 response_needed 為 true 時才將對話送入 CoreDB，減少不必要的寫入。
若使用多模態訊息（如圖片），需提供合法 URI 與 MIME type；否則會被 OpenAI API 拒絕。