بخش 3.3 · مدل‌ها، پیام‌ها و ابزارها

پیام‌ها و بلوک‌های محتوا

Messages and content blocks

فهرست مطالب
  1. چهار نوع پیام
  2. بلوک‌های محتوا
  3. ورودی چندوجهی
  4. تکه‌ها
  5. هرس کردن پیام‌ها

ورودی و خروجی هر مدلی، فهرستی از چهار نوع پیام است؛ و content_blocks محتوای هر ارائه‌دهنده‌ای را در قالب بلوک‌های تایپ‌شده‌ی یکسان می‌خواند.

ایجنت خود را از یک ارائه‌دهنده به ارائه‌دهنده‌ای دیگر منتقل می‌کنید و ناگهان کدی که متن استدلال مدل را می‌خواند از کار می‌افتد. یک ارائه‌دهنده آن را در بلوک thinking می‌گذارد و دیگری در بلوک reasoning. هر دو در واقع همان content یک AIMessage هستند، اما در دو قالب متفاوت.

در پایان این بخش، می‌توانید انواع پیام‌ها را بسازید و فراخوانی ابزار را از یک AIMessage بخوانید. همچنین می‌توانید محتوا را از طریق بلوک‌های استانداردی بخوانید که میان ارائه‌دهنده‌های مختلف یکسان می‌مانند.

چهار نوع پیام

پیام (Message): یک مدخل در گفت‌وگو، شامل یک نوع، یک content و یک id اختیاری.

پیام SystemMessage حاوی دستورالعمل‌هاست، HumanMessage نوبت گفت‌وگوی کاربر را نگه می‌دارد، AIMessage خروجی مدل را در بر دارد و ToolMessage نتیجه‌ی ابزار را ذخیره می‌کند. این هم یک نمونه گفت‌وگو در قالب دیکشنری:

یک گفتگو در قالب شیءهای پیام capture/out/02-messages.txt
  {
    "type": "HumanMessage",
    "content": "What is 2 + 3?"
  },
  {
    "type": "AIMessage",
    "content": "",
    "tool_calls": [
      {
        "name": "add",
        "args": {
          "a": 2,
          "b": 3
        },
        "id": "call_1",
        "type": "tool_call"
      }
    ]
  },
  {
    "type": "ToolMessage",
    "content": "5",
    "name": "add",
    "tool_call_id": "call_1",
    "status": "success"
  },
  {
    "type": "AIMessage",
    "content": "The sum is 5.",
    "usage_metadata": {
      "input_tokens": 12,
      "output_tokens": 6,
      "total_tokens": 18
    }
  }

بخش نخست فایل. پیام SystemMessage بریده شده است.

فراخوانی ابزار (Tool call): یک مدخل در AIMessage.tool_calls شامل name، آرگومان‌های پارس‌شده (args) و یک id. پیام ToolMessage متناظری که به آن پاسخ می‌دهد، همین شناسه را در tool_call_id خود دارد.

پیام AIMessage که درخواست ابزار دارد، content خالی دارد. درخواست آن در tool_calls قرار می‌گیرد که از متن JSON ارائه‌دهنده پارس شده است. فیلد usage_metadata نیز تعداد توکن‌ها را در صورت گزارش ارائه‌دهنده ذخیره می‌کند. شکل جایگاه هر فیلد را نشان می‌دهد.

فیلدهای یک AIMessage و ToolMessage متناظر آنفراخوانی ابزار در AIMessage.tool_calls قرار می‌گیرد نه در content، و ToolMessage پاسخ‌دهنده id آن را در tool_call_id تکرار می‌کند.
فیلدهای یک AIMessage و ToolMessage متناظر آن سه کارت خوانده‌شده از یک اجرای ایجنت. نخستین کارت AIMessage است که یک ابزار را درخواست می‌کند: content برابر ""، شناسه lc_run--<uuid-2>-0، و tool_calls با نام add، آرگومان‌های {a: 2, b: 3} و شناسه <uuid-3>. دومین کارت ToolMessage است که به آن پاسخ می‌دهد: content برابر "5"، نام add، شناسه tool_call_id برابر <uuid-3> و وضعیت success. یک خط‌چین شناسه <uuid-3> در فراخوانی ابزار را به tool_call_id متصل می‌کند. سومین کارت در پایین، AIMessage نهایی با content برابر "2 + 3 = 5." و بدون tool_calls است که حلقه را پایان می‌دهد. پاسخ یک ارائه‌دهنده واقعی همچنین حاوی usage_metadata است، مانند 12 توکن ورودی و 6 توکن خروجی. AIMessage content "" id lc_run--<uuid-2>-0 tool_calls .name add .args {a: 2, b: 3} .id <uuid-3> ToolMessage content "5" name add id <uuid-4> tool_call_id <uuid-3> status success id یکسان فراخوانی بعدی مدل هر دو را می‌خواند AIMessage، پاسخ نهایی content "2 + 3 = 5." tool_calls هیچ، پس ایجنت متوقف می‌شود usage_metadata 12 ورودی، 6 خروجی، در صورت گزارش ارائه‌دهنده The request for a tool is in tool_calls, already parsed, and its content is empty. پیام ToolMessage شناسه فراخوانی‌ای که به آن پاسخ می‌دهد را تکرار می‌کند.
کارت سمت چپ همان AIMessage است که تابع add را درخواست می‌کند، و کارت سمت راست ToolMessage است که به آن پاسخ می‌دهد. خط واصل، دو فیلدی را که حاوی call_1 هستند به هم متصل می‌کند. برگرفته از capture/out/02-messages.txt و capture/out/06-agent-run.txt.

می‌توانید دیکشنری‌ها و تاپل‌های ساده را هم پاس بدهید. create_agent و تمام مدل‌های چت، ساختار {"role": "user", "content": "hi"} را به HumanMessage و ("assistant", "hello") را به AIMessage تبدیل می‌کنند:

دیکشنری‌ها و تاپل‌ها پس از convert_to_messages capture/out/02-messages.txt
  {
    "type": "HumanMessage",
    "content": "hi"
  },
  {
    "type": "AIMessage",
    "content": "hello"
  },
  {
    "type": "SystemMessage",
    "content": "be brief"
  }

بلوک‌های محتوا

بلوک محتوا (Content block): بخشی تایپ‌شده از یک پیام؛ دیکشنری با یک type مانند text، reasoning، image، file یا tool_call.

مستندات می‌گویند که هر پیامی یک ویژگی content_blocks دارد که هنگام خواندن، content را به بلوک‌های تایپ‌شده‌ی استاندارد پارس می‌کند {{docs oss/python/langchain/messages}}. در همان صفحه آمده است که بلوک‌های محتوا به content اضافه می‌شوند و جایگزین آن نمی‌شوند {{docs oss/python/langchain/messages}}. بنابراین content ساختار ارائه‌دهنده را حفظ می‌کند و content_blocks شکل استاندارد را در اختیارتان می‌گذارد.

کیت، یک AIMessage با ساختار محتوایی Anthropic می‌سازد: یک بلوک thinking با امضا (signature)، و سپس یک بلوک متنی. ویژگی content_blocks آن را به صورت بلوک‌های استاندارد می‌خواند:

محتوای ارائه‌دهنده خوانده‌شده به‌صورت بلوک‌های استاندارد capture/out/02-messages.txt
  {
    "type": "reasoning",
    "reasoning": "Add the numbers.",
    "extras": {
      "signature": "sig"
    }
  },
  {
    "type": "text",
    "text": "The sum is 5."
  }
]

.text -> 'The sum is 5.'

بلوک thinking به reasoning تبدیل شد و فیلد ارائه‌دهنده که نام استانداردی نداشت به extras رفت. ویژگی .text بلوک‌های متنی را در قالب یک رشته به هم پیوند می‌دهد. این ویژگی در نسخه‌ی پین‌شده یک property است. کدهایی که متد .text() را صدا می‌زنند همچنان کار می‌کنند، اما اخطار می‌دهند.

در یک AIMessage که حاوی فراخوانی ابزار و محتوای خالی است، content_blocks برای هر فراخوانی یک بلوک tool_call دارد. بنابراین با یک حلقه روی content_blocks، متن، استدلال و فراخوانی‌های ابزار را به ترتیب وقوع می‌خوانید.

ورودی چندوجهی

یک HumanMessage می‌تواند فهرستی از بلوک‌های استاندارد را در content نگه دارد. کیت یک بلوک متنی، یک تصویر با URL و یک PDF به صورت base64 ارسال می‌کند:

یک پیام انسانی چندحالته capture/out/02-messages.txt
      {
        "type": "text",
        "text": "Describe this image."
      },
      {
        "type": "image",
        "url": "https://example.com/cat.png"
      },
      {
        "type": "file",
        "base64": "JVBERi0=",
        "mime_type": "application/pdf"
      }

لیست content پیام.

پکیج هر ارائه‌دهنده، این بلوک‌ها را به فرمت درخواست خودش تبدیل می‌کند. مشخصات مدل (model profile) مشخص می‌کند که مدل چه ورودی‌هایی مانند image_inputs و pdf_inputs را می‌پذیرد. بخش 3.2 نمونه‌ای از این مشخصات را نشان می‌دهد.

تکه‌ها

تکه (Chunk): بخشی از یک پیام که مدل به صورت جریانی ارسال می‌کند، مانند AIMessageChunk. تکه‌ها با عملگر + به یک پیام تبدیل می‌شوند.

فراخوانی‌های ابزار هم تکه‌تکه استریم می‌شوند. هر tool_call_chunk تکه‌ای از آرگومان‌ها را در قالب متن نگه می‌دارد. وقتی تکه‌ها با هم جمع می‌شوند، این بخش‌ها به هم پیوند می‌خورند و فراخوانی پارس‌شده در tool_calls ظاهر می‌شود:

تکه‌های فراخوانی ابزار پس از تجمیع capture/out/02-messages.txt
{
  "tool_call_chunks": [
    {
      "name": "add",
      "args": "{\"a\": 2, \"b\": 3}",
      "id": "call_1",
      "index": 0,
      "type": "tool_call_chunk"
    }
  ],
  "tool_calls": [
    {
      "name": "add",
      "args": {
        "a": 2,
        "b": 3
      },
      "id": "call_1",
      "type": "tool_call"
    }
  ]
}

نسخه‌ی 1.7.0 از langchain-core نحوه‌ی گزارش آرگومان‌های فراخوانی ابزار را در حین دریافت استریم تغییر داد. بخش 5 رویدادهای استریم مربوط به این نسخه‌ی پین‌شده را نشان می‌دهد.

هرس کردن پیام‌ها

تابع trim_messages پیام‌های انتهایی را تا جایی که در سهمیه‌ی توکن جا شوند نگه می‌دارد. با max_tokens=3 و شمارنده‌ای که برای هر پیام یک واحد می‌شمارد، پیام سیستمی و دو پیام آخر حفظ شدند. با start_on="human" فقط پیام سیستمی باقی ماند، چون هیچ برشی از پیام‌های حفظ‌شده با پیام کاربر شروع نمی‌شد:

تابع trim_messages با پارامتر start_on human capture/out/02-messages.txt
the same with start_on='human':
[
  {
    "type": "SystemMessage",
    "content": "You are terse."
  }
]

نتیجه‌ی اول با یک ToolMessage شروع می‌شود که AIMessage متناظر آن حذف شده است. بیشتر ارائه‌دهنده‌ها نتیجه‌ی ابزاری را که فراخوانیِ آن نباشد رد می‌کنند. بنابراین پیام‌ها را در مرز نوبت گفت‌وگو هرس کنید و خروجی هرس را بسنجید.

منابع: capture/out/02-messages.txt، capture/out/06-agent-run.txt؛ docs.langchain.com در docs commit 04d4d4a (بخش‌های oss/python/langchain/messages، oss/python/releases/changelog)؛ libs/core/langchain_core/messages در langchain==1.5.0.

ترجمه‌ی فارسی Messages and content blocks از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما