پشتیبانی آمازون بدراک از خروجی‌های ساختاریافته در مدل‌های کلود آنتروپیک

آمازون بدراک اکنون در تمام مدل‌های کلود آنتروپیک، در هر دو نقطه پایانی bedrock-runtime و bedrock-mantle، از خروجی‌های ساختاریافته پشتیبانی می‌کند؛ البته این قابلیت در مناطقی در دسترس است که مدل مربوطه ارائه می‌شود.

چه از طریق Boto3 و رابط‌های برنامه‌نویسی bedrock-runtime با کلود ارتباط برقرار کنید و چه از طریق Messages API و نقطه پایانی bedrock-mantle، اکنون می‌توانید پاسخ‌های JSON دریافت کنید که با ساختار تعریف‌شده در طرح‌واره مطابقت دارند. در نتیجه، دیگر نیازی به پیاده‌سازی منطق سفارشی برای تجزیه پاسخ‌ها، تلاش مجدد یا پردازش پس از تولید نیست.

کاربردهای عملی

خروجی‌های ساختاریافته کلود در آمازون بدراک امکان خودکارسازی وظایف قابل‌اعتماد و منطبق با طرح‌واره را در صنایع مختلف فراهم می‌کنند. از جمله کاربردهای آن می‌توان به استخراج تمام فیلدهای موردنیاز از گزارش‌های درآمد مالی و اسناد انطباق، تبدیل یادداشت‌های بالینی به داده‌های پرونده الکترونیکی سلامت (EHR) و تکمیل کاتالوگ محصولات با اطلاعات یکپارچه و اعتبارسنجی‌شده اشاره کرد. همچنین می‌توان از این قابلیت برای شناسایی اصطلاحات کلیدی، طرف‌های قرارداد و تعهدات در اسناد قراردادی یا هدایت هوشمند تیکت‌های پشتیبانی استفاده کرد؛ به‌گونه‌ای که مقاصد، احساسات و موجودیت‌های شناسایی‌شده همواره با مدل داده‌ای برنامه مطابقت داشته باشند.

خروجی‌های ساختاریافته چه تغییری در آمازون بدراک ایجاد می‌کنند؟

خروجی‌های ساختاریافته از روش رمزگشایی محدودشده (Constrained Decoding) استفاده می‌کنند تا انطباق با طرح‌واره JSON در همان مرحله تولید توکن‌ها تضمین شود، نه پس از پایان تولید. مدل توکن‌هایی تولید نمی‌کند که با طرح‌واره تعریف‌شده ناسازگار باشند. به این ترتیب، قالب‌بندی خروجی از فرایندی احتمالاتی به فرایندی قطعی تبدیل می‌شود.

اکنون دو سازوکار مکمل در هر دو نقطه پایانی آمازون بدراک در دسترس است:

این قابلیت چه مزایایی برای شما دارد؟

هر پاسخ در قالب JSON معتبر ارائه می‌شود؛ بنابراین، دیگر با خطاهای JSON.parse() یا استثناهای ناشی از تجزیه داده‌ها مواجه نخواهید شد. پاسخ‌ها همچنین از نظر نوع داده ایمن هستند: نوع هر فیلد رعایت می‌شود و فیلدهای الزامی همواره وجود دارند. از آنجا که خروجی‌ها همیشه با طرح‌واره شما مطابقت دارند، برای مدیریت موارد ناسازگار با طرح‌واره نیازی به تلاش مجدد نیست و در نتیجه، یکپارچه‌سازی قابل‌اعتمادتر می‌شود. خروجی‌های ساختاریافته همچنین پاسخ را به فیلدهای تعریف‌شده در طرح‌واره محدود می‌کنند. این کار تعداد توکن‌های خروجی را کاهش می‌دهد و می‌تواند هزینه استنتاج را در بارهای کاری پرتراکنش پایین بیاورد. این ویژگی‌ها خروجی‌های ساختاریافته را برای استفاده در محیط عملیاتی آماده می‌کنند و امکان استقرار در مقیاس بزرگ را بدون نیاز به کدنویسی اضافی برای اعتبارسنجی طرح‌واره فراهم می‌سازند.

مدل‌های پشتیبانی‌شده و دسترس‌پذیری

خروجی‌های ساختاریافته با استنتاج دسته‌ای (Batch Inference) سازگار هستند؛ بنابراین، می‌توانید حجم زیادی از درخواست‌ها را به‌صورت غیرهم‌زمان پردازش کنید و همچنان خروجی‌هایی مطابق با طرح‌واره دریافت کنید. این قابلیت در نقطه پایانی bedrock-runtime از استنتاج بین‌منطقه‌ای نیز پشتیبانی می‌کند و امکان استفاده از آن را در مناطق مختلف AWS بدون نیاز به تنظیمات اضافی فراهم می‌سازد. اگر به پاسخ‌های بلادرنگ نیاز دارید، می‌توانید پاسخ‌های ساختاریافته را به‌صورت جریانی و در قالب رویدادهای نوع‌دار دریافت کنید.

نحوه عملکرد

هنگامی که درخواستی حاوی یک طرح‌واره JSON ارسال می‌کنید، مراحل زیر در پشت صحنه انجام می‌شوند:

1. اعتبارسنجی طرح‌واره: آمازون بدراک طرح‌واره JSON شما را بر اساس زیرمجموعه پشتیبانی‌شده از استاندارد JSON Schema Draft 2020-12 اعتبارسنجی می‌کند.
2. کامپایل دستور زبان: برای طرح‌واره‌های جدید، آمازون بدراک یک ساختار دستور زبان کامپایل‌شده ایجاد می‌کند. به همین دلیل، ممکن است درخواست نخست کمی بیشتر طول بکشد.
3. ذخیره‌سازی در حافظه نهان: دستور زبان‌های کامپایل‌شده به مدت ۲۴ ساعت در حافظه نهان نگهداری می‌شوند و درخواست‌های بعدی را سریع‌تر می‌کنند.
4. تولید محدودشده: مدل توکن‌هایی تولید می‌کند که حاصل آن‌ها JSON معتبری منطبق با طرح‌واره شماست.

نکات مربوط به عملکرد

از نظر عملکرد، نخستین درخواست با یک طرح‌واره جدید ممکن است زمان بیشتری ببرد؛ زیرا آمازون بدراک پیش از آغاز تولید، ساختار دستور زبان را کامپایل می‌کند. پس از این مرحله اولیه، درخواست‌های بعدی با همان طرح‌واره سربار پردازشی اندکی خواهند داشت، زیرا دستور زبان کامپایل‌شده در حافظه نهان قرار دارد. این حافظه نهان به حساب کاربری شما اختصاص دارد و از نخستین استفاده به مدت ۲۴ ساعت اعتبار دارد. تغییر ساختار طرح‌واره JSON باعث بی‌اعتبار شدن حافظه نهان و اجرای دوباره فرایند کامپایل می‌شود؛ اما تغییر صرفاً در فیلدهای نام یا توضیحات، دستور زبان ذخیره‌شده را بی‌اعتبار نمی‌کند.

شروع کار: خروجی‌های ساختاریافته با API مربوط به InvokeModel در bedrock-runtime

API مربوط به InvokeModel بدنه درخواست بومی آنتروپیک را دریافت می‌کند؛ بنابراین، طرح‌واره باید در فیلد output_config.format به‌صورت یک شیء JSON قرار گیرد، نه یک رشته JSON. مثال زیر نشان می‌دهد که چگونه می‌توان با استفاده از boto3 و یک مدل کلود آنتروپیک، اطلاعات ساختاریافته سرنخ فروش را از ایمیل مشتری استخراج کرد:

پایتون

import boto3
import json

REGION = "us-east-1" # منطقه دلخواه خود را انتخاب کنید
bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)

# تعریف طرح‌واره JSON برای خروجی ساختاریافته
schema = {
 "type": "object",
 "properties": {
 "name": {"type": "string", "description": "نام مشتری"},
 "email": {"type": "string", "description": "نشانی ایمیل مشتری"},
 "plan_interest": {"type": "string", "description": "طرح محصول موردعلاقه"},
 "demo_requested": {"type": "boolean", "description": "آیا درخواست نمایش محصول ثبت شده است؟"}
 },
 "required": ["name", "email", "plan_interest", "demo_requested"],
 "additionalProperties": False
}

# ارسال درخواست با خروجی ساختاریافته از طریق API مربوط به InvokeModel
# (استفاده مجدد از طرح‌واره تعریف‌شده برای مثال Converse)
response = bedrock_runtime.invoke_model(
 modelId="global.anthropic.claude-sonnet-5-5",
 body=json.dumps({
 "anthropic_version": "bedrock-2023-05-31",
 "max_tokens": 512,
 "messages": [
 {"role": "user", "content": (
 "Paulo Santos ([email protected]) is interested in our Enterprise plan "
 "and wants to schedule a demo for next Tuesday at 2pm."
 )}
 ],
 "output_config": {"format": {"type": "json_schema", "schema": schema}}
 })
)

body = json.loads(response["body"].read())

# پیش از تجزیه پاسخ، دلیل توقف را بررسی کنید
if body["stop_reason"] == "end_turn":
 result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
 print(json.dumps(json.loads(result_text), indent=2))
elif body["stop_reason"] == "max_tokens":
 print("پاسخ ناقص است؛ مقدار max_tokens را افزایش دهید و دوباره تلاش کنید.")

نمونه خروجی JSON:

{
 "name": "Paulo Santos",
 "email": "[email protected]",
 "plan_interest": "Enterprise",
 "demo_requested": true
}

پاسخ با طرح‌واره شما مطابقت دارد و به اعتبارسنجی اضافی نیاز نیست.

برای مشاهده مثال‌های بیشتر از نحوه استفاده از API، از جمله Messages API، به دفترچه نمونه مراجعه کنید.

استفاده سخت‌گیرانه از ابزارها در گردش‌کارهای عامل‌محور

Amazon Bedrock Mantle برای برنامه‌های عامل‌محوری طراحی شده است که از ابزارهای سمت سرور، استنتاج پس‌زمینه و مکالمات دارای وضعیت استفاده می‌کنند. با قابلیت استفاده سخت‌گیرانه از ابزارها در نقطه پایانی bedrock-mantle، اکنون می‌توانید اطمینان حاصل کنید که پارامترهای ابزار دقیقاً با طرح‌واره ورودی شما مطابقت دارند. مثال زیر نحوه تعریف ابزاری با اعمال سخت‌گیرانه طرح‌واره را نشان می‌دهد:

import json
from anthropic import AnthropicBedrockMantle

# استفاده مجدد از کلاینت ایجادشده در مثال Messages API
client = AnthropicBedrockMantle(aws_region="us-east-1")

message = client.messages.create(
 model="anthropic.claude-sonnet-5",
 max_tokens=512,
 messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
 tools=[
 {
 "name": "get_weather",
 "description": "Get the current weather for a specified location",
 "strict": True,
 "input_schema": {
 "type": "object",
 "properties": {
 "location": {
 "type": "string",
 "description": "The city and state, e.g., San Francisco, CA"
 },
 "unit": {
 "type": "string",
 "enum": ["celsius", "fahrenheit"],
 "description": "Temperature unit"
 }
 },
 "required": ["location", "unit"],
 "additionalProperties": False
 }
 }
 ]
)

# ورودی‌های ابزار با طرح‌واره مطابقت دارند
for block in message.content:
 if block.type == "tool_use":
 print(f"Tool: {block.name}")
 print(f"Input: {json.dumps(block.input, indent=2)}")

با تنظیم strict: true، ورودی ابزار تولیدشده توسط مدل دقیقاً به ساختار طرح‌واره محدود می‌شود. فیلد location همواره از نوع رشته است و فیلد unit نیز فقط می‌تواند یکی از مقادیر celsius یا fahrenheit را داشته باشد. مدل نمی‌تواند فیلدی خارج از طرح‌واره اضافه کند؛ بنابراین، ورودی ابزار فقط شامل موارد تعریف‌شده در طرح‌واره خواهد بود.

این قابلیت به‌ویژه برای کاربردهای عامل‌محور در Amazon Bedrock Mantle ارزشمند است؛ جایی که مدل‌ها گردش‌کارهای چندمرحله‌ای را با ابزارهای سمت سرور، مانند جست‌وجوی وب و مفسر کد، هماهنگ می‌کنند.

مهم‌ترین کاربردهای خروجی ساختاریافته کلود

خروجی‌های ساختاریافته در سه الگوی رایج، پیچیدگی مدیریت خطا را بیش از همه کاهش می‌دهند:

• استخراج داده: استخراج فیلدها از فاکتورها، قراردادها، ایمیل‌ها و رونوشت‌ها و تبدیل آن‌ها به JSON منطبق با طرح‌واره، به‌گونه‌ای که داده‌ها آماده ورود به پایگاه‌های داده یا سامانه‌های مدیریت ارتباط با مشتری (CRM) باشند.
• فراخوانی قابل‌اعتماد ابزارها توسط عامل‌ها: اعتبارسنجی آرگومان‌های ابزار بر اساس طرح‌واره‌های آن‌ها در زمان تولید، به‌طوری که گردش‌کارهای عامل‌محور چندمرحله‌ای بدون خطاهای ناشی از ورودی‌های نامعتبر اجرا شوند.
• طبقه‌بندی در مقیاس بزرگ: دسته‌بندی تیکت‌ها، سرنخ‌های فروش یا محتوا بر اساس قصد، اولویت و احساسات برای مسیردهی، نظارت بر محتوا و ارزیابی.

مدل Claude Haiku 5.5 برای مدیریت قابل‌اعتماد بارهای کاری سریع و تکراری، مانند خلاصه‌سازی، فشرده‌سازی، پرس‌وجوهای پایگاه داده و درخواست‌های طبقه‌بندی، مناسب است. مثال زیر نشان می‌دهد که چگونه می‌توان با استفاده از API مربوط به Invoke و مدل Haiku 5.5 داده‌های ورودی را طبقه‌بندی و مسیردهی کرد:

import boto3
import json

REGION = "us-east-1" # منطقه دلخواه خود را انتخاب کنید
bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)

# طرح‌واره طبقه‌بندی: مقادیر enum خروجی را به مجموعه‌ای ثابت از برچسب‌ها محدود می‌کنند
schema = {
 "type": "object",
 "properties": {
 "category": {
 "type": "string",
 "enum": ["billing", "technical", "account", "sales", "other"],
 "description": "دسته اصلی تیکت"
 },
 "priority": {
 "type": "string",
 "enum": ["low", "medium", "high", "urgent"],
 "description": "میزان فوریت بر اساس تأثیر بر کسب‌وکار"
 },
 "sentiment": {
 "type": "string",
 "enum": ["positive", "neutral", "negative"],
 "description": "احساسات مشتری"
 },
 "escalate": {"type": "boolean", "description": "آیا بررسی فوری توسط انسان لازم است؟"},
 "reason": {"type": "string", "description": "توجیه یک‌جمله‌ای برای طبقه‌بندی"}
 },
 "required": ["category", "priority", "sentiment", "escalate", "reason"],
 "additionalProperties": False
}

ticket = (
 "Our production API calls have been failing with 500 errors since this morning. "
 "We're losing orders every minute. This is the second outage this month!"
)

# ارسال درخواست با خروجی ساختاریافته از طریق API مربوط به InvokeModel
response = bedrock_runtime.invoke_model(
 modelId="global.anthropic.claude-haiku-5-5",
 body=json.dumps({
 "anthropic_version": "bedrock-2023-05-31",
 "max_tokens": 512,
 "system": "You are a support ticket classifier. Classify the ticket accurately.",
 "messages": [
 {"role": "user", "content": f"Classify this support ticket:\n\n{ticket}"}
 ],
 "output_config": {"format": {"type": "json_schema", "schema": schema}}
 })
)

body = json.loads(response["body"].read())

# پیش از تجزیه پاسخ، دلیل توقف را بررسی کنید
if body["stop_reason"] == "end_turn":
 result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
 result = json.loads(result_text)
 print(json.dumps(result, indent=2))
 # مسیردهی تیکت بر اساس برچسب‌های معتبر و تضمین‌شده
 if result["escalate"]:
 print(f"Escalating to on-call: {result['category']} / {result['priority']}")
elif body["stop_reason"] == "max_tokens":
 print("پاسخ ناقص است؛ مقدار max_tokens را افزایش دهید و دوباره تلاش کنید.")

الزامات و بهترین روش‌ها

برای استفاده مؤثر از خروجی‌های ساختاریافته در آمازون بدراک، دستورالعمل‌های زیر را رعایت کنید:

1. برای تمام اشیا، مقدار additionalProperties: false را تنظیم کنید: این تنظیم برای کارکرد خروجی‌های ساختاریافته الزامی است. بدون آن، طرح‌واره شما پذیرفته نخواهد شد.
2. از نام‌ها و توضیحات روشن برای فیلدها استفاده کنید: مدل‌ها برای تشخیص داده‌هایی که باید استخراج کنند، از نام ویژگی‌ها و توضیحات آن‌ها کمک می‌گیرند. نام‌های روشنی مانند customer_email عملکرد بهتری از نام‌های عمومی مانند field1 دارند.
3. برای مقادیر محدود از enum استفاده کنید: اگر فیلدی مجموعه محدودی از مقادیر معتبر دارد، با استفاده از enum گزینه‌های مجاز را مشخص کنید.
4. با ساختار ساده شروع کنید و سپس پیچیدگی را افزایش دهید: ابتدا حداقل فیلدهای ضروری را تعریف کنید و به‌تدریج پیچیدگی را افزایش دهید. کامپایل طرح‌واره‌های ساده سریع‌تر است، اشکال‌زدایی آن‌ها آسان‌تر انجام می‌شود و از آنجا که طرح‌واره بخشی از حجم محموله درخواست Converse API را تشکیل می‌دهد، اندازه درخواست نیز کمتر خواهد بود.
5. برای بهره‌مندی از حافظه نهان، طرح‌واره‌ها را دوباره استفاده کنید: برنامه را طوری طراحی کنید که طرح‌واره‌ها در درخواست‌های مختلف تکراراً استفاده شوند. حافظه نهان دستور زبان با اعتبار ۲۴ساعته، عملکرد درخواست‌های تکراری را بهبود می‌دهد.
6. دلیل توقف را در هر پاسخ بررسی کنید: دو وضعیت ممکن است به پاسخ‌هایی منجر شوند که با طرح‌واره مطابقت ندارند: امتناع مدل از پاسخ‌گویی به دلایل ایمنی و رسیدن به محدودیت توکن پیش از تکمیل پاسخ. هر دو وضعیت را در کد خود مدیریت کنید.
7. پیش از استقرار، با داده‌های واقع‌گرایانه آزمایش کنید: طرح‌واره‌های خود را با ورودی‌هایی مشابه داده‌های محیط عملیاتی اعتبارسنجی کنید. موارد مرزی در داده‌های واقعی اغلب مشکلات طراحی طرح‌واره را آشکار می‌کنند.

برای آشنایی با بهترین روش‌های بیشتر و توصیه‌های مربوط به طراحی طرح‌واره، به بخش خروجی‌های ساختاریافته در راهنمای کاربر آمازون بدراک مراجعه کنید.

قابلیت‌های پشتیبانی‌شده در JSON Schema

1. تمام انواع پایه: object، array، string، integer، number، boolean و null.
2. enum؛ فقط برای رشته‌ها، اعداد، مقادیر بولی یا null.
3. const، anyOf و allOf، با محدودیت‌هایی مشخص.
4. $ref، $def و definitions؛ فقط برای ارجاع‌های داخلی.
5. قالب‌های رشته‌ای: date-time، time، date، duration، email، hostname، uri، ipv4، ipv6 و uuid.
6. ویژگی minItems برای آرایه‌ها، فقط با مقادیر ۰ و ۱.

قابلیت‌های پشتیبانی‌نشده

این کلیدواژه‌ها توسط API پذیرفته می‌شوند، اما هنگام تولید خروجی اعمال نمی‌شوند. در صورت استفاده از آن‌ها، درخواست با موفقیت پاسخ داده می‌شود، ولی مدل همچنان ممکن است مقادیری تولید کند که محدودیت‌های مربوطه را نقض کنند. بنابراین، به‌جای اتکا به طرح‌واره برای اعمال این محدودیت‌ها، باید آن‌ها را در برنامه خود اعتبارسنجی کنید.

1. طرح‌واره‌های بازگشتی.
2. ارجاع‌های خارجی $ref.
3. محدودیت‌های عددی، از جمله minimum، maximum و multipleOf.
4. محدودیت‌های رشته‌ای، از جمله minLength و maxLength.
5. تنظیم additionalProperties روی هر مقداری به‌جز false.

جمع‌بندی

خروجی‌های ساختاریافته برای مدل‌های کلود آنتروپیک در آمازون بدراک، قابلیت اطمینانی را فراهم می‌کنند که برنامه‌های هوش مصنوعی در محیط عملیاتی به آن نیاز دارند. این قابلیت اکنون در هر دو نقطه پایانی bedrock-runtime و bedrock-mantle در دسترس است. با ترکیب قالب خروجی JSON Schema و استفاده سخت‌گیرانه از ابزارها، می‌توانید خطوط پردازش داده‌ای بسازید که به اعتبارسنجی اضافی نیاز ندارند. همچنین می‌توانید گردش‌کارهای عامل‌محور قابل‌اعتماد و برنامه‌های هوش مصنوعی آماده محیط عملیاتی را بدون نیاز به منطق سفارشی برای تجزیه پاسخ‌ها یا تلاش مجدد ایجاد کنید.

خروجی‌های ساختاریافته برای کلود در آمازون بدراک اکنون به‌صورت عمومی در دسترس هستند. برای کسب اطلاعات بیشتر، به مستندات آمازون بدراک مراجعه کنید و دفترچه نمونه را بررسی کنید.

خروجی‌های JSON اعتبارسنجی‌شده و منطبق با طرح‌واره می‌توانند کدام گردش‌کارها را در سازمان شما بهبود دهند؟ دیدگاه‌ها و پرسش‌های خود را در بخش نظرات مطرح کنید.