پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

ورودی‌های فایل 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 base	chunk، embed، ذخیره، retrieve و سپس پاسخ با `/v1/responses`

URL فایل‌ها

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

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

BashJavaScriptPython

bash

curl "https://api.avalai.ir/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "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.5",
  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.5",
    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 به مدل ارجاع می‌دهیم.

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

BashJavaScriptPython

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.5",
    "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.5",
  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.5",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "file_id": file.id,
                },
                {
                    "type": "input_text",
                    "text": "اولین اژدها در کتاب چیست؟",
                },
            ],
        }
    ],
)

print(response.output_text)

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

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

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

BashJavaScriptPython

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.5",
"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.5",
  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.5",
    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 کنید.

منابع مرتبط

پردازش 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 آن پردازش کنید:

PythonJavaScriptBash

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 محلی استفاده کنید:

PythonJavaScriptBash

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:

PythonBash

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.5",
    "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 استفاده می‌کند.

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

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

URL فایل‌ها ​

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

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

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

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

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

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

منابع مرتبط ​

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

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

OCR با URL فایل PDF ​

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

OCR با تصاویر ​

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

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

نمونه خروجی ​

درک سند ​

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

منابع مرتبط ​

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

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

URL فایل‌ها

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

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

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

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

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

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

منابع مرتبط

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

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

OCR با URL فایل PDF

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

OCR با تصاویر

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

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

نمونه خروجی

درک سند

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

منابع مرتبط