داشبورد توسعه‌دهنده
پرسش از هوش مصنوعی
پرسش از هوش مصنوعی

ورودی‌های فایل PDF ​

انتخاب مسیر PDF: برای درک یک‌باره PDF از /v1/responses با input_file استفاده کنید؛ وقتی می‌خواهید یک بار upload کنید و بعدا با file_id ارجاع دهید، از Files API با purpose="user_data" استفاده کنید؛ و برای retrieval روی تعداد زیادی سند، RAG دستی مناسب‌تر است.

بیاموزید چگونه از فایل‌های PDF به عنوان ورودی به API AvalAI استفاده کنید.

مدل‌های AvalAI با قابلیت‌های بینایی می‌توانند فایل‌های PDF را به‌صورت آیتم‌های input_file در Responses API بپذیرند. وقتی ذخیره‌سازی فایل فعال نیست، PDF را به شکل URL خارجی (file_url) یا داده Base64 (file_data) ارسال کنید؛ وقتی ذخیره‌سازی فایل برای حساب و endpoint شما فعال باشد، می‌توانید فایل را یک بار از طریق Files API آپلود کنید و سپس شناسه برگشتی (file_id) را ارجاع دهید.

چگونه کار می‌کند ​

پردازش فایل به نوع فایل بستگی دارد:

  • فایل‌های PDF: برای مدل‌های دارای قابلیت بینایی، AvalAI از الگوی سازگار با OpenAI پیروی می‌کند و هم متن استخراج‌شده و هم تصویر صفحات را در context مدل قرار می‌دهد. این کار زمانی مفید است که نمودارها، فرم‌ها یا جدول‌ها اطلاعاتی داشته باشند که در متن ساده دیده نمی‌شود.
  • سندهای غیر PDF و فایل‌های متنی: متن استخراج می‌شود، اما تصویرها یا نمودارهای embedded وارد context مدل نمی‌شوند. اگر وفاداری بصری مهم است، ابتدا فایل را به PDF تبدیل کنید.
  • Spreadsheetها: فایل‌های جدولی را مثل داده ساختاریافته ببینید، نه متن طولانی. برای worksheetهای کوچک می‌توانید فایل را مستقیم ارسال کنید؛ برای join، aggregation یا sheetهای بزرگ، داده را در برنامه خود استخراج کنید و خلاصه‌ای فشرده بفرستید یا از گردش‌کار retrieval استفاده کنید.
  • مجموعه سندهای بزرگ: همه اسناد را در یک درخواست قرار ندهید. برای بازیابی روی فایل‌های زیاد از RAG دستی با embeddings یا الگوهای file search استفاده کنید.
کاربردسبک ورودی پیشنهادی
PDF عمومی یا موقتfile_url در درخواست Responses
PDF خصوصی که چند بار استفاده می‌شودupload به /v1/files با purpose="user_data"، سپس ارسال file_id
PDF محلی کوچک بدون ماندگاریfile_data با data URL مبتنی بر Base64
تعداد زیادی PDF یا پرسش‌های تکرارشونده از knowledge basechunk، embed، ذخیره، retrieve و سپس پاسخ با /v1/responses

URL فایل‌ها ​

وقتی PDF از قبل روی یک URL معتبر HTTPS در دسترس است و لازم نیست در فضای ذخیره‌سازی فایل AvalAI نگهداری شود، از file_url استفاده کنید.

ارسال PDF مبتنی بر URL به Responses ​

bash
curl "https://api.avalai.ir/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "تعهدات اصلی این PDF را خلاصه کن."
          },
          {
            "type": "input_file",
            "file_url": "https://example.com/contract.pdf"
          }
        ]
      }
    ]
  }'
javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "تعهدات اصلی این PDF را خلاصه کن.",
        },
        {
          type: "input_file",
          file_url: "https://example.com/contract.pdf",
        },
      ],
    },
  ],
});

console.log(response.output_text);
python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.6-luna",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "تعهدات اصلی این PDF را خلاصه کن.",
                },
                {
                    "type": "input_file",
                    "file_url": "https://example.com/contract.pdf",
                },
            ],
        }
    ],
)

print(response.output_text)

آپلود فایل‌ها ​

در مثال زیر، ابتدا یک PDF را با استفاده از Files API آپلود می‌کنیم، سپس به شناسه فایل آن در یک درخواست API به مدل ارجاع می‌دهیم.

آپلود یک فایل برای استفاده در پاسخ ​

bash
curl https://api.avalai.ir/v1/files \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -F purpose="user_data" \
  -F file="@draconomicon.pdf"

curl "https://api.avalai.ir/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_file",
            "file_id": "file-6F2ksmvXxt4VdoqmHRw6kL"
          },
          {
            "type": "input_text",
            "text": "اولین اژدها در کتاب چیست؟"
          }
        ]
      }
    ]
  }'
javascript
import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const file = await client.files.create({
  file: fs.createReadStream("draconomicon.pdf"),
  purpose: "user_data",
});

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_file",
          file_id: file.id,
        },
        {
          type: "input_text",
          text: "اولین اژدها در کتاب چیست؟",
        },
      ],
    },
  ],
});

console.log(response.output_text);
python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"], base_url="https://api.avalai.ir/v1"
)

file = client.files.create(file=open("draconomicon.pdf", "rb"), purpose="user_data")

response = client.responses.create(
    model="gpt-5.6-luna",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "file_id": file.id,
                },
                {
                    "type": "input_text",
                    "text": "اولین اژدها در کتاب چیست؟",
                },
            ],
        }
    ],
)

print(response.output_text)

فایل‌های کدگذاری شده Base64 ​

می‌توانید ورودی‌های فایل PDF را به صورت ورودی‌های کدگذاری شده Base64 نیز ارسال کنید.

کدگذاری Base64 یک فایل برای استفاده در پاسخ ​

bash
PDF_BASE64=$(base64 -i draconomicon.pdf) # در لینوکس از -w 0 برای عدم شکست خط استفاده کنید

curl "https://api.avalai.ir/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
"model": "gpt-5.6-luna",
"input": [
{
"role": "user",
"content": [
{
"type": "input_file",
"filename": "draconomicon.pdf",
"file_data": "data:application/pdf;base64,'"$PDF_BASE64"'"
},
{
"type": "input_text",
"text": "اولین اژدها در کتاب چیست؟"
}
]
}
]
}'
javascript
import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const data = fs.readFileSync("draconomicon.pdf");
const base64String = data.toString("base64");

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_file",
          filename: "draconomicon.pdf",
          file_data: `data:application/pdf;base64,${base64String}`,
        },
        {
          type: "input_text",
          text: "اولین اژدها در کتاب چیست؟",
        },
      ],
    },
  ],
});

console.log(response.output_text);
python
import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"], base_url="https://api.avalai.ir/v1"
)

with open("draconomicon.pdf", "rb") as f:
    data = f.read()

base64_string = base64.b64encode(data).decode("utf-8")

response = client.responses.create(
    model="gpt-5.6-luna",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "filename": "draconomicon.pdf",
                    "file_data": f"data:application/pdf;base64,{base64_string}",
                },
                {
                    "type": "input_text",
                    "text": "اولین اژدها در کتاب چیست؟",
                },
            ],
        },
    ],
)

print(response.output_text)

ملاحظات استفاده ​

در زیر چند نکته وجود دارد که هنگام استفاده از ورودی‌های PDF باید در نظر داشته باشید.

استفاده از توکن

routeهای Responses دارای قابلیت بینایی می‌توانند هم متن استخراج‌شده و هم تصویر هر صفحه PDF را وارد context مدل کنند، حتی وقتی صفحه بیشتر متن است. پیش از استفاده در مقیاس production، سندهای نماینده را تست کنید، usage.input_tokens را log بگیرید و اثر قیمت‌گذاری ورودی PDF را بررسی کنید. اطلاعات بیشتر در مورد قیمت‌گذاری.

محدودیت‌های حجم فایل

برای ورودی‌های فایل در سبک Responses، هر فایل را کمتر از ۵۰ مگابایت نگه دارید و مجموع payload فایل‌ها در یک درخواست را نیز زیر ۵۰ مگابایت نگه دارید. بعضی ارائه‌دهندگان upstream ممکن است برای مدل‌ها یا endpointهای خاص محدودیت سخت‌گیرانه‌تری اعمال کنند؛ در این حالت PDFهای بزرگ را تقسیم کنید یا از retrieval استفاده کنید.

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

پردازش PDF همراه با تصویر صفحات به مدلی نیاز دارد که هم ورودی متن و هم ورودی تصویر را پشتیبانی کند، مثل مدل‌های OpenAI دارای قابلیت بینایی فعلی. ویژگی‌های مدل را اینجا بررسی کنید.

هدف آپلود فایل

شما می‌توانید این فایل‌ها را با هر هدفی به Files API آپلود کنید، اما توصیه می‌کنیم از هدف user_data برای فایل‌هایی که قصد دارید به عنوان ورودی مدل استفاده کنید، استفاده نمایید.

Guardrailهای دقت

وقتی پاسخ باید قابل audit باشد، از مدل page number، quote قابل مشاهده، نام جدول یا heading بخش را بخواهید. برای قراردادها، فاکتورها، اسناد پزشکی و گزارش‌های مالی، پیش از اقدام بر اساس مقدارهای استخراج‌شده، چند صفحه نمونه را بیرون از مدل verify کنید.

استخراج و یکسان‌سازی داده‌های چندصفحه‌ای ​

برای فاکتورها، فرم‌ها و گزارش‌ها، استخراج وفادار به منبع را از ساختاری که برنامه شما نیاز دارد جدا کنید. این الگو از دفترچه استخراج و تبدیل داده در OpenAI Cookbook و راهنمای قالب JSON خام، با پیوند به نسخه ثابت منابع، اقتباس شده است. همه فیلدها و مبلغ‌های نمونه زیر ساختگی‌اند.

وقتی مدل انتخابی AvalAI ورودی PDF را پشتیبانی می‌کند، از روش‌های input_file در Responses که بالاتر توضیح داده شد استفاده کنید. دفترچه OpenAI برای گردش‌کار Chat Completions خود صفحات PDF را به تصویر تبدیل می‌کند؛ این یک روش ارسال در سمت برنامه است و برای همه درخواست‌های PDF در Responses الزامی نیست. اگر به این روش نیاز دارید، صفحات را در برنامه خود به تصویر تبدیل کنید و از راهنمای بینایی کمک بگیرید. پیش از انتخاب هر روش، مدل دقیق، مسیر API و قالب خروجی را بررسی کنید.

۱. شواهد خام هر صفحه را نگه دارید ​

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

برنامه شما source_id و شماره صفحه در PDF اصلی را، با شمارش از 1، تعیین می‌کند و کنار داده استخراج‌شده نگه می‌دارد. هنگام تقسیم PDF به فایل‌های کوچک‌تر، این ارتباط را حفظ کنید. حالت JSON برای شکل‌های متغیر داده خام هر صفحه مفید است، اما فقط نحو JSON را محدود می‌کند. مانند دفترچه OpenAI، رکوردهای صفحه را در برنامه خود در یک آرایه گردآوری کنید و رکوردهای خام را جدا از خروجی یکسان‌سازی‌شده نگه دارید.

json
[
  {
    "source_id": "synthetic-invoice-001",
    "page": 1,
    "data": {
      "Rechnungsnummer": "DEMO-001",
      "Rechnungsdatum": "15.10.2026",
      "Währung": "EUR",
      "Positionen": [
        {
          "Beschreibung": "Service A",
          "Netto": "100,00",
          "Steuersatz": "20 %",
          "Steuer": "20,00",
          "Brutto": "120,00"
        }
      ],
      "Kundenreferenz": null
    },
    "evidence": {
      "invoice_date": "Rechnungsdatum: 15.10.2026",
      "line_item": "Service A | 100,00 | 20 % | 20,00 | 120,00"
    }
  },
  {
    "source_id": "synthetic-invoice-001",
    "page": 2,
    "data": {
      "Currency": "EUR",
      "Gross total": "120.00",
      "Customer reference": null
    },
    "evidence": {
      "gross_total": "Gross total EUR 120.00"
    }
  }
]

در این نمونه، صفحه اول عنوان‌های آلمانی و جداکننده اعشاری ویرگول دارد؛ صفحه دوم از عنوان‌های انگلیسی و نقطه اعشاری استفاده می‌کند. مقدار مرجع مشتری در هر دو صفحه null است. رشته‌های evidence متن قابل مشاهده منبع را نشان می‌دهند، اما ثابت نمی‌کنند که مدل آن را درست خوانده است؛ هر نقل‌قول و ارتباط آن با شماره صفحه را با سند اصلی بررسی کنید.

۲. داده را در ساختاری نسخه‌دار یکسان‌سازی کنید ​

پیش از تبدیل داده، نام‌های ثابت فیلدها، مقدارهای مجاز null، واحد پول، قرارداد تاریخ و دقت مبلغ‌ها را مشخص کنید. وقتی مسیر انتخابی از json_schema پشتیبانی می‌کند، از خروجی‌های ساختاریافته استفاده کنید؛ در غیر این صورت حالت JSON را به کار ببرید و نتیجه کامل را در برنامه خود اعتبارسنجی کنید. شماره فاکتور و شناسه‌های دیگر را دقیق نگه دارید و آن‌ها را ترجمه نکنید.

در این نمونه، تاریخ منبع صریحاً میلادی و با قالب DD.MM.YYYY است. آن را به 2026-10-15 تبدیل می‌کنیم؛ مبلغ‌های دارای ویرگول اعشاری به رشته‌های اعشاری تبدیل می‌شوند و نرخ مالیات 20 % به نسبت 0.20 تبدیل می‌شود. تقویم را حدس نزنید و تاریخی مبهم مانند 03/04/2026 را خودسرانه تفسیر نکنید. مقدار اصلی را نگه دارید و تاریخ‌ها یا مبلغ‌های نامشخص را برای بازبینی ارجاع دهید.

رکورد زیر یک پیشنهاد یکسان‌سازی‌شده است. رشته‌های اعشاری دقت موردنظر را برای محاسبات اعشاری در سمت برنامه حفظ می‌کنند؛ این یک قرارداد آگاهانه برای فیلدهاست، نه الزام API در AvalAI.

json
{
  "schema_version": "invoice_v1",
  "source_id": "synthetic-invoice-001",
  "invoice_number": "DEMO-001",
  "invoice_date": "2026-10-15",
  "currency": "EUR",
  "customer_reference": null,
  "line_items": [
    {
      "description": "Service A",
      "net_amount": "100.00",
      "tax_rate": "0.20",
      "tax_amount": "20.00",
      "gross_amount": "120.00",
      "source_page": 1
    }
  ],
  "gross_total": "120.00",
  "evidence": {
    "invoice_date": {
      "page": 1,
      "quote": "Rechnungsdatum: 15.10.2026"
    },
    "gross_total": {
      "page": 2,
      "quote": "Gross total EUR 120.00"
    }
  }
}

۳. پیش از ورود به پایگاه داده اعتبارسنجی کنید ​

پس از بررسی امتناع مدل، خروجی ناقص و خطاهای درخواست، رکورد کامل را اعتبارسنجی کنید:

  • نسخه ساختار، فیلدهای الزامی، کدهای مجاز واحد پول و نوع شناسه‌ها را بررسی کنید. مرجع مشتری که در سند وجود ندارد باید null بماند و به مرجعی ساختگی تبدیل نشود.
  • مبلغ‌ها را با محاسبات اعشاری یا عدد صحیح بر حسب کوچک‌ترین واحد پول پردازش کنید. رشته تاریخ باید تاریخ واقعی و معتبر در تقویم مربوط باشد؛ قالب درست به‌تنهایی اعتبار تاریخ را ثابت نمی‌کند.
  • مبلغ سطرها و مالیات را با جمع‌های قابل مشاهده سند و با سیاست صریح گردکردن تطبیق دهید. در این نمونه، 100.00 + 20.00 = 120.00 است. جمع تکرارشده یا مبلغ منتقل‌شده از صفحه قبلی را سطر تازه‌ای حساب نکنید.
  • پوشش صفحات و سطرهای مورد انتظار جدول را بررسی کنید، شواهد را با PDF تطبیق دهید و مقدارهای استخراج‌شده را از جمع‌ها یا مقدارهای دیگری که برنامه محاسبه کرده است جدا نگه دارید.
  • واحد پول نامشخص، تاریخ مبهم، خانه ناخوانا، ناسازگاری جمع‌ها یا صفحه مفقود را برای بازبینی انسانی ارجاع دهید. پیش از ثبت مالی یا اقدام حساس دیگر، بازبینی لازم است؛ انطباق با ساختار خروجی مجوز اقدام نیست.
  • فقط رکوردهای اعتبارسنجی‌شده را با عملیات پایگاه داده تحت کنترل برنامه و پرس‌وجوهای پارامتری وارد کنید. از تراکنش و کلید ثابت سند یا کار استفاده کنید تا تلاش دوباره برای یک صفحه یا تبدیل داده، رکورد تکراری نسازد. نسخه دستور به مدل و ساختار، مدل، شناسه درخواست و نتیجه اعتبارسنجی را برای تشخیص خطا نگه دارید و متن حساس سند را بی‌دلیل در گزارش‌های رخداد کپی نکنید.

پردازش تعداد زیادی سند ​

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

منابع مرتبط ​

پردازش OCR با Mistral OCR 4 ​

AvalAI از mistral-ocr-4-0 برای OCR مبتنی بر layout و درک سند پشتیبانی می‌کند. این مدل Markdown را همراه با bounding box، طبقه‌بندی نوع بلوک و اطلاعات confidence در ۱۷۰ زبان استخراج می‌کند. mistral-ocr-latest اکنون به mistral-ocr-4-0 اشاره می‌کند و قیمت OCR 4 را دارد؛ وقتی بازتولیدپذیری اهمیت دارد از شناسه نسخه‌دار استفاده کنید.

هشدار

توجه: Mistral OCR URLهای معتبر HTTP/HTTPS و داده‌های سند کدگذاری‌شده با Base64 را می‌پذیرد. فقط وقتی route انتخابی AvalAI از file ID برای آن workflow پشتیبانی می‌کند از v1/files استفاده کنید؛ در غیر این صورت URL یا data URL را مستقیم به endpoint OCR بدهید.

ویژگی‌های کلیدی ​

  • استخراج متن با حفظ ساختار و سلسله مراتب سند در قالب Markdown
  • ارائه bounding box برای هایلایت، citation و گردش‌کارهای redaction
  • طبقه‌بندی بلوک‌هایی مانند عنوان، جدول، معادله و امضا
  • ارائه اطلاعات confidence برای اعتبارسنجی و بازبینی انسانی
  • پشتیبانی از layoutهای پیچیده شامل متن چندستونی و محتوای ترکیبی
  • پشتیبانی از ۱۷۰ زبان در ۱۰ گروه زبانی
  • قیمت $0.004 برای هر صفحه OCR و $0.005 برای هر صفحه annotation‌شده

OCR با URL فایل PDF ​

شما می‌توانید یک سند PDF را با ارائه URL آن پردازش کنید:

python
import os
from mistralai import Mistral

client = Mistral(
    server_url="https://api.avalai.ir", api_key=os.environ["AVALAI_API_KEY"]
)

document_param = {
    "type": "document_url",
    "document_url": "https://arxiv.org/pdf/1805.04770",
}

ocr_response = client.ocr.process(
    model="mistral-ocr-4-0",
    document=document_param,
    pages=list(range(0, 100)),  # پردازش تا 100 صفحه
)

print(ocr_response)
javascript
import { Mistral } from "mistralai";

const client = new Mistral({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir",
});

const documentParam = {
  type: "document_url",
  document_url: "https://arxiv.org/pdf/1805.04770",
};

const ocrResponse = await client.ocr.process({
  model: "mistral-ocr-4-0",
  document: documentParam,
  pages: Array.from({ length: 100 }, (_, i) => i), // پردازش تا 100 صفحه
});

console.log(ocrResponse);
bash
curl https://api.avalai.ir/v1/ocr \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
 "model": "mistral-ocr-4-0",
 "document": {
 "type": "document_url",
 "document_url": "https://arxiv.org/pdf/1805.04770"
 },
 "include_image_base64": true
}' -o ocr_output.json

OCR با PDF کدگذاری شده با Base64 ​

وقتی به ذخیره‌سازی قابل استفاده مجدد فایل نیاز ندارید، از کدگذاری Base64 برای پردازش مستقیم PDF محلی استفاده کنید:

python
import base64
import os
from mistralai import Mistral

# خواندن و کدگذاری فایل PDF
with open("document.pdf", "rb") as f:
    pdf_data = f.read()

base64_pdf = base64.b64encode(pdf_data).decode("utf-8")
document_url = f"data:application/pdf;base64,{base64_pdf}"

# پردازش PDF کدگذاری شده
client = Mistral(
    server_url="https://api.avalai.ir", api_key=os.environ["AVALAI_API_KEY"]
)

document_param = {"type": "document_url", "document_url": document_url}

ocr_response = client.ocr.process(
    model="mistral-ocr-4-0",
    document=document_param,
    pages=list(range(0, 100)),  # پردازش تا 100 صفحه
)

print(ocr_response)
javascript
import fs from "fs";
import { Mistral } from "mistralai";

// خواندن و کدگذاری فایل PDF
const pdfData = fs.readFileSync("document.pdf");
const base64Pdf = pdfData.toString("base64");
const documentUrl = `data:application/pdf;base64,${base64Pdf}`;

// پردازش PDF کدگذاری شده
const client = new Mistral({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir",
});

const documentParam = {
  type: "document_url",
  document_url: documentUrl,
};

const ocrResponse = await client.ocr.process({
  model: "mistral-ocr-4-0",
  document: documentParam,
  pages: Array.from({ length: 100 }, (_, i) => i),
});

console.log(ocrResponse);
bash
# تبدیل PDF به base64
PDF_BASE64=$(base64 -i document.pdf) # در لینوکس از -w 0 برای عدم شکست خط استفاده کنید

# پردازش PDF کدگذاری شده
curl https://api.avalai.ir/v1/ocr \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
"model": "mistral-ocr-4-0",
"document": {
"type": "document_url",
"document_url": "data:application/pdf;base64,'"$PDF_BASE64"'"
},
"include_image_base64": true
}' -o ocr_output.json

OCR با تصاویر ​

Mistral OCR می‌تواند تصاویر را به دو روش پردازش کند:

استفاده از URL مستقیم تصویر: ​

bash
curl https://api.avalai.ir/v1/ocr \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
"model": "mistral-ocr-4-0",
"document": {
"type": "image_url",
"image_url": "https://raw.githubusercontent.com/mistralai/cookbook/refs/heads/main/mistral/ocr/receipt.png"
}
}' -o ocr_output.json

استفاده از تصاویر کدگذاری شده با base64: ​

python
import base64
import os
from mistralai import Mistral

# خواندن و کدگذاری فایل تصویر
with open("document.jpg", "rb") as f:
    image_data = f.read()

base64_image = base64.b64encode(image_data).decode("utf-8")
image_url = f"data:image/jpeg;base64,{base64_image}"

# پردازش تصویر کدگذاری شده
client = Mistral(
    server_url="https://api.avalai.ir", api_key=os.environ["AVALAI_API_KEY"]
)

document_param = {"type": "image_url", "image_url": image_url}

ocr_response = client.ocr.process(
    model="mistral-ocr-4-0",
    document=document_param,
)

print(ocr_response)
bash
# تبدیل تصویر به base64
IMAGE_BASE64=$(base64 -i document.jpg) # در لینوکس از -w 0 برای عدم شکست خط استفاده کنید

# پردازش تصویر کدگذاری شده
curl https://api.avalai.ir/v1/ocr \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
"model": "mistral-ocr-4-0",
"document": {
"type": "image_url",
"image_url": "data:image/jpeg;base64,'"$IMAGE_BASE64"'"
}
}' -o ocr_output.json

نمونه خروجی ​

API OCR هم محتوای متن استخراج شده در قالب مارک‌داون و هم متادیتا در مورد ساختار سند را برمی‌گرداند:

json
{
  "pages": [
    {
      "index": 1,
      "markdown": "# LEVERAGING UNLABELED DATA TO PREDICT OUT-OF-DISTRIBUTION PERFORMANCE \n\nSaurabh Garg*<br>Carnegie Mellon University<br>sgarg2@andrew.cmu.edu<br>Sivaraman Balakrishnan<br>Carnegie Mellon University<br>sbalakri@andrew.cmu.edu<br>Zachary C. Lipton<br>Carnegie Mellon University<br>zlipton@andrew.cmu.edu\n\n## Behnam Neyshabur\n\nGoogle Research, Blueshift team\nneyshabur@google.com\n\nHanie Sedghi<br>Google Research, Brain team<br>hsedghi@google.com\n\n\n#### Abstract\n\nReal-world machine learning deployments are characterized by mismatches between the source (training) and target (test) distributions that may cause performance drops...",
      "images": [],
      "dimensions": {
        "dpi": 200,
        "height": 2200,
        "width": 1700
      }
    }
    // صفحات اضافی...

  ],
  "model": "mistral-ocr-4-0",
  "usage_info": {
    "pages_processed": 3,
    "doc_size_bytes": null
  }
}

درک سند ​

می‌توانید Mistral OCR را با مدل‌های زبانی ترکیب کنید تا امکان تعامل زبان طبیعی با محتوای سند را فراهم کنید. این به شما امکان می‌دهد با پرسیدن سؤالات به زبان طبیعی، اطلاعات و بینش‌ها را از اسناد استخراج کنید:

bash
curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
 "model": "mistral-small-latest",
 "messages": [
 {
 "role": "user",
 "content": [
 {
 "type": "text",
 "text": "آخرین جمله در سند چیست"
 },
 {
 "type": "document_url",
 "document_url": "https://arxiv.org/pdf/1805.04770"
 }
 ]
 }
 ]
}'
نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `mistral-small-latest` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

bash
curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-5.6-luna",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Summarize the uploaded file."
          },
          {
            "type": "input_file",
            "file_id": "file_abc123"
          }
        ]
      }
    ]
  }'
  • messages → input
  • پیام سیستمی → instructions یا آیتم developer
  • choices[0].message.content → response.output_text
  • برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

ملاحظات استفاده ​

  • محدودیت‌های اندازه فایل: فایل‌های سند آپلود شده نباید از 50 مگابایت بیشتر باشند و نباید بیش از 1000 صفحه داشته باشند.
  • فرمت‌های تصویر پشتیبانی شده: PNG (.png)، JPEG (.jpeg و .jpg)، WEBP (.webp) و GIF غیر متحرک با فقط یک فریم (.gif).
  • قیمت‌گذاری: هزینه mistral-ocr-4-0 برابر $0.004 برای هر صفحه OCR است. annotation سند یا تصویر $0.005 برای هر صفحه annotation‌شده هزینه دارد. alias مدل mistral-ocr-latest نیز از همین قیمت OCR 4 استفاده می‌کند.

منابع مرتبط ​