چندرسانه‌ای در Chat Completions

در Chat Completions، پیام کاربر همیشه فقط یک رشته متنی نیست. اگر مدل و ارائه‌دهنده انتخابی پشتیبانی کنند، می‌توانید متن را همراه تصویر، فایل یا بعضی رسانه‌های دیگر بفرستید.

نکته اصلی: چندرسانه‌ای بودن یک قابلیت وابسته به مدل است. گدارAI قرارداد درخواست، احراز هویت، دسترسی، بودجه و پایش را یکپارچه می‌کند؛ اما خود مدل باید نوع ورودی مورد نظر شما را پشتیبانی کند.

پیام چندرسانه‌ای چگونه ساخته می‌شود؟

در درخواست ساده، content یک رشته است. در درخواست چندرسانه‌ای، content به آرایه‌ای از بخش‌ها تبدیل می‌شود:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "این تصویر را برای کاربر توصیف کن." },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_WORKSPACE.godarai.ir/assets/sample-image.png"
      }
    }
  ]
}

هر بخش باید نوع مشخص داشته باشد. بخش متنی معمولاً type: "text" است و تصویر معمولاً با image_url فرستاده می‌شود.

شروع سریع با تصویر

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "این تصویر چه چیزی را نشان می‌دهد؟"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://YOUR_WORKSPACE.godarai.ir/assets/sample-image.png"
          }
        }
      ]
    }
  ]
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "این تصویر چه چیزی را نشان می‌دهد؟"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://YOUR_WORKSPACE.godarai.ir/assets/sample-image.png"
          }
        }
      ]
    }
  ]
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "این تصویر چه چیزی را نشان می‌دهد؟"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://YOUR_WORKSPACE.godarai.ir/assets/sample-image.png"
          }
        }
      ]
    }
  ]
}'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.chat.completions.create(
    "model": "openai:default:gpt-4o",
    messages=[
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "این تصویر چه چیزی را نشان می‌دهد؟"
            },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://YOUR_WORKSPACE.godarai.ir/assets/sample-image.png"
              }
            }
          ]
        }
      ]

)

print(response)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.chat.completions.create({
  "model": "openai:default:gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "این تصویر چه چیزی را نشان می‌دهد؟"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://YOUR_WORKSPACE.godarai.ir/assets/sample-image.png"
          }
        }
      ]
    }
  ]
});

console.log(response);

نشانی تصویر باید برای ارائه‌دهنده مدل قابل دسترس باشد. اگر تصویر پشت شبکه خصوصی یا نیازمند نشست کاربری باشد، مدل نمی‌تواند آن را بخواند.

ارسال تصویر با base64

وقتی تصویر عمومی نیست، می‌توانید آن را به data URL تبدیل کنید:

import base64
from openai import OpenAI

def encode_image(path: str) -> str:
    with open(path, "rb") as file:
        return base64.b64encode(file.read()).decode("utf-8")

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

image_data = encode_image("sample.png")

response = client.chat.completions.create(
    model="openai:default:gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "متن داخل این تصویر را استخراج کن."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{image_data}"
                    },
                },
            ],
        }
    ],
)

data URL درخواست را بزرگ‌تر می‌کند. برای فایل‌های بزرگ، اثر آن روی زمان پاسخ، هزینه و ثبت رخداد را بسنجید.

کیفیت پردازش تصویر

بعضی مدل‌ها از گزینه‌ای مثل detail پشتیبانی می‌کنند:

{
  "type": "image_url",
  "image_url": {
    "url": "https://YOUR_WORKSPACE.godarai.ir/assets/invoice.png",
    "detail": "high"
  }
}

راهنمای انتخاب:

• low برای پیش‌نمایش، هزینه کمتر و پاسخ سریع‌تر.
• high برای استخراج دقیق‌تر، نمودار، فاکتور یا متن ریز.
• auto وقتی می‌خواهید تصمیم را به مدل و ارائه‌دهنده بسپارید.

فایل و PDF

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

{
  "role": "user",
  "content": [
    { "type": "text", "text": "این PDF را در پنج نکته خلاصه کن." },
    {
      "type": "file",
      "file": {
        "filename": "guide.pdf",
        "file_data": "data:application/pdf;base64,..."
      }
    }
  ]
}

برای فایل‌های بزرگ، قبل از استفاده گسترده، محدودیت اندازه، زمان پاسخ و هزینه را با همان مدل مجاز فضای کاری خود آزمایش کنید.

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

اگر کار شما تخصصی و تک‌منظوره است، API تخصصی را انتخاب کنید:

• برای بردارسازی متن از Embeddings استفاده کنید.
• برای تولید تصویر از APIهای تصویر استفاده کنید.
• برای تبدیل صوت به متن یا ترجمه صوت، APIهای صوتی مناسب‌ترند.

چندرسانه‌ای در Chat Completions زمانی بهترین انتخاب است که به فهم رسانه در کنار گفت‌وگو یا استدلال متنی نیاز دارید.

اثر روی حافظه نهان و ابزارها

درخواست‌های چندرسانه‌ای معمولاً مثل درخواست‌های متنی ساده قابل استفاده در حافظه نهان نیستند. اگر هم‌زمان ابزارها را هم فعال کنید، مسیر عیب‌یابی پیچیده‌تر می‌شود. بهتر است:

• اول درخواست متن + تصویر را بدون ابزار پایدار کنید.
• سپس ابزارها را اضافه کنید.
• برای هر نوع رسانه، سناریوی تست جدا داشته باشید.

خطاهای رایج

• مدل انتخابی ورودی تصویر یا فایل را پشتیبانی نمی‌کند.
• نشانی فایل برای ارائه‌دهنده قابل دسترس نیست.
• data URL پیشوند یا base64 نامعتبر دارد.
• مدل در دسترسی توکن یا کاربر مجاز نیست.
• حجم رسانه باعث خطا، زمان پاسخ زیاد یا هزینه غیرمنتظره می‌شود.

جمع‌بندی

قابلیت چندرسانه‌ای در Chat Completions زمانی قدرتمند است که آن را با مدل سازگار، ورودی کوچک و قابل دسترس، و پایش دقیق مصرف همراه کنید. همیشه پشتیبانی واقعی مدل را معیار بگیرید، نه صرفاً شکل ظاهری درخواست را.