پرش به مطلب اصلی
جستجو

درون‌خطی‌سازی تصویر

گاردریل inline_image_urls آدرس‌های HTTP و HTTPS داخل متن را پیدا می‌کند و اگر پاسخ هر آدرس یک تصویر معتبر باشد، آن URL را با data URL مبتنی بر Base64 جایگزین می‌کند. این نوع برای زمانی مفید است که متن ورودی شامل لینک تصویر است و می‌خواهید تصویر پیش از ارسال به مدل در خود متن قرار بگیرد.

اطلاع

این گاردریل تنها نوع این دسته است که «اصلاح محتوا» (operation: "mutate") انجام می‌دهد. یعنی متن عبوری از درگاه ممکن است تغییر کند و نتیجه تغییر با وضعیت mutated در guardrail_checks ثبت شود.

چه زمانی استفاده کنید؟​

از inline_image_urls برای این کارها استفاده کنید:

  • تبدیل URL تصویر داخل متن به مقداری مثل data:image/png;base64,....
  • کاهش وابستگی ارائه‌دهنده مدل به دسترسی مستقیم به دامنه تصویر.
  • محدودکردن دامنه، اندازه و مهلت دریافت تصویر پیش از ادامه مسیر.

اگر تصویر در پیام چندبخشی و فیلد ساخت‌یافته image_url ارسال می‌شود، ابتدا قابلیت‌ها و محدوده پشتیبانی گاردریل‌ها را بخوانید؛ این گاردریل فقط متن را بازنویسی می‌کند.

رفتار اجرایی​

این نوع فقط از «اصلاح محتوا» (operation: "mutate") پشتیبانی می‌کند. گدارAI هر URL با http یا https را در متن پیدا می‌کند، تصویر را دریافت می‌کند و این کنترل‌ها را انجام می‌دهد:

  • URL شامل username یا password نباشد.
  • اگر «دامنه‌های مجاز» وارد شده است، دامنه URL دقیقاً در همان فهرست باشد.
  • به‌صورت پیش‌فرض، دامنه به IP خصوصی، loopback، link-local یا unspecified resolve نشود.
  • پاسخ HTTP موفق باشد و Content-Type آن با image/ شروع شود.
  • اندازه بدنه پاسخ از «حداکثر حجم تصویر» بیشتر نباشد.

همین کنترل‌ها روی redirectها هم اعمال می‌شوند. اگر تبدیل انجام شود، وضعیت mutated و علت Image URLs converted to inline data ثبت می‌شود.

هشدار

این گاردریل به URLهای داخل متن درخواست شبکه می‌زند. در محیط عملیاتی، «دامنه‌های مجاز» را محدود نگه دارید و «اجازه به آدرس‌های شبکه خصوصی» را فقط وقتی فعال کنید که مقصدها کاملاً تحت کنترل شما هستند.

تنظیمات​

عنوان UIمقدار APIتوضیح
حداکثر حجم تصویرmax_bytesحداکثر اندازه هر تصویر بر حسب بایت. مقدار پیش‌فرض 1048576 است.
دامنه‌های مجازallowed_hostsهر خط یک دامنه مجاز است. بدون wildcard بررسی می‌شود. اگر خالی بماند، همه دامنه‌های عمومی مجازند.
مهلت زمانی (میلی‌ثانیه)timeout_msمهلت دریافت هر URL. مقدار پیش‌فرض 3000 است.
اجازه به آدرس‌های شبکه خصوصیallow_private_networksپیش‌فرض خاموش است. فقط در شبکه کنترل‌شده فعال کنید.

نمونه تعریف​

{
  "slug": "inline-cdn-images",
  "name": "Inline trusted CDN images",
  "type": "inline_image_urls",
  "operation": "mutate",
  "enforcement": "enforce",
  "enabled": true,
  "config": {
    "max_bytes": 1048576,
    "allowed_hosts": ["images.godarai.ir"],
    "timeout_ms": 3000,
    "allow_private_networks": false
  }
}

نمونه استفاده​

x-godarai-guardrails: {"llm_input_guardrails":["guardrails/inline-cdn-images"]}

اگر متن ورودی این باشد:

این تصویر را بررسی کن: https://images.godarai.ir/chart.png

پس از اصلاح محتوا، URL تصویر با مقداری که با data:image/png;base64, شروع می‌شود جایگزین خواهد شد.

نکته

برای شروع، این گاردریل را روی ورودی مدل بگذارید، نه خروجی. کاربرد رایج آن آماده‌سازی درخواست قبل از رسیدن به مدل است.

رفتار خطا​

اگر دریافت تصویر، بررسی دامنه، نوع محتوا یا محدودیت اندازه ناموفق باشد:

شیوه اعمالرفتار
عدم عبور و لاگدرخواست یا پاسخ متوقف می‌شود.
عبور همراه با نشانه‌گذاریخطا در نتیجه بررسی ثبت می‌شود و متن اصلی ادامه پیدا می‌کند.
عدم عبور - بدون لاگخطای اجرای خود گاردریل مسیر را مانند حالت معمول متوقف نمی‌کند.

علت‌های رایج شامل این موارد است:

  • image URL host is not allowed
  • URL did not return an image
  • image exceeds max size
  • image URL credentials are not allowed

محدودیت‌ها و نکات امنیتی​

  • این گاردریل همه URLهای HTTP(S) داخل متن را نامزد تصویر فرض می‌کند. URL یک صفحه وب معمولی می‌تواند خطای URL did not return an image بسازد.
  • فقط URL داخل محتوای متنی را تغییر می‌دهد و فیلد ساخت‌یافته image_url در پیام چندبخشی را بازنویسی نمی‌کند.
  • دریافت تصویر در زمان درخواست انجام می‌شود و حافظه نهان داخلی ندارد؛ تعداد URLها روی زمان پاسخ اثر مستقیم دارد.
  • بررسی تصویر بودن بر اساس سرآیند Content-Type است، نه تحلیل کامل فایل تصویر.
  • گاردریل آماده برای این نوع وجود ندارد؛ باید گاردریل اختصاصی بسازید.

پرسش‌های پرتکرار​

آیا wildcard در دامنه‌های مجاز پشتیبانی می‌شود؟​

نه. دامنه‌ها به‌صورت host دقیق بررسی می‌شوند. برای هر دامنه مجاز، مقدار همان host را جداگانه وارد کنید.

اگر URL به دامنه دیگری redirect شود چه می‌شود؟​

دامنه مقصد redirect هم با «دامنه‌های مجاز» و محدودیت شبکه خصوصی بررسی می‌شود. اگر مجاز نباشد، اجرای گاردریل خطا می‌دهد.

گام بعدی​