> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-d2fddb8a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# إدخالات الملفات

> أرفق ملفات PDF ومستندات Office والنصوص والبيانات وشفرة المصدر بطلبات chat completion في Venice للتلخيص والأسئلة والأجوبة والتحويل.

تتيح لك إدخالات الملفات إرفاق المستندات وملفات المصدر مباشرة بطلب `/chat/completions`. تستخرج Venice الملف إلى نص قبل إرساله إلى النموذج المحدد، حتى تتمكن من طرح أسئلة، أو التلخيص، أو المقارنة، أو تحويل محتوى الملف دون بناء المحلل اللغوي الخاص بك أولًا.

استخدم إدخالات الملفات عندما يعتمد prompt على محتويات مستند أو جدول بيانات أو ملف markdown أو ملف JSON أو ملف شفرة. هذه مدخلات نطاقها الطلب، وليست تخزين ملفات دائم، لذا قم بتضمين الملف في كل طلب يحتاجه.

<Info>
  تستخدم إدخالات الملفات مصفوفة محتوى الدردشة المتوافقة مع OpenAI. أضف كتلة محتوى بـ `type: "file"` وقدّم محتوى الملف في `file.file_data`.
</Info>

## أنواع الملفات المدعومة

يقبل chat API إدخالات الملفات إما كعناوين URL لبيانات base64 أو كعناوين URL متاحة بشكل عام.

الحد الأقصى لحجم الملف هو **25 ميجابايت لكل ملف**، يُقاس بعد فك ترميز عنوان URL لبيانات base64 أو بعد جلب عنوان URL.

| الفئة            | التنسيقات                                                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| المستندات        | PDF, DOCX, PPTX                                                                                                                  |
| جداول البيانات   | XLSX, XLS, CSV                                                                                                                   |
| النصوص والبيانات | TXT, Markdown, JSON                                                                                                              |
| شفرة المصدر      | معظم ملفات الشفرة الشائعة، بما في ذلك `.py`, `.js`, `.ts`, `.c`, `.cpp`, `.java`, `.go`, `.rs`, `.ps1`, `.sh`, `.yaml`, و `.sql` |

<Note>
  يتم استخراج الملفات إلى نص قبل الاستدلال. يحتسب النص المستخرج ضمن سياق إدخال النموذج، لذا اختر نموذجًا بكمية كافية من `availableContextTokens` للملف بالإضافة إلى تعليماتك والإجابة المتوقعة.
</Note>

## الاستخدام الأساسي

أرسل مصفوفة `messages` حيث يكون `content` لرسالة المستخدم مصفوفة من كتل النص والملفات:

<CodeGroup>
  ```python Python theme={null}
  import base64
  import os
  from pathlib import Path

  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["VENICE_API_KEY"],
      base_url="https://api.venice.ai/api/v1",
  )

  path = Path("q3-report.pdf")
  file_data = "data:application/pdf;base64," + base64.b64encode(path.read_bytes()).decode("utf-8")

  response = client.chat.completions.create(
      model="openai-gpt-55",
      messages=[
          {
              "role": "user",
              "content": [
                  {
                      "type": "text",
                      "text": "Summarize this report in five bullets and list the main risks.",
                  },
                  {
                      "type": "file",
                      "file": {
                          "file_data": file_data,
                          "filename": "q3-report.pdf",
                      },
                  },
              ],
          }
      ],
  )

  print(response.choices[0].message.content)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";
  import { readFile } from "node:fs/promises";

  const client = new OpenAI({
    apiKey: process.env.VENICE_API_KEY,
    baseURL: "https://api.venice.ai/api/v1",
  });

  const pdf = await readFile("q3-report.pdf");
  const fileData = `data:application/pdf;base64,${pdf.toString("base64")}`;

  const response = await client.chat.completions.create({
    model: "openai-gpt-55",
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "Summarize this report in five bullets and list the main risks.",
          },
          {
            type: "file",
            file: {
              file_data: fileData,
              filename: "q3-report.pdf",
            },
          },
        ],
      },
    ],
  });

  console.log(response.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  PDF_BASE64=$(base64 < q3-report.pdf | tr -d '\n')

  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d @- <<EOF
  {
    "model": "openai-gpt-55",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Summarize this report in five bullets and list the main risks."
          },
          {
            "type": "file",
            "file": {
              "file_data": "data:application/pdf;base64,$PDF_BASE64",
              "filename": "q3-report.pdf"
            }
          }
        ]
      }
    ]
  }
  EOF
  ```
</CodeGroup>

## عناوين URL للملفات

إذا كان الملف مستضافًا بالفعل على عنوان URL عام لـ HTTP أو HTTPS، فمرر عنوان URL في `file_data` بدلًا من ترميزه بـ base64:

```json theme={null}
{
  "model": "openai-gpt-55",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Identify the governing law, renewal terms, and termination rights in this agreement."
        },
        {
          "type": "file",
          "file": {
            "file_data": "https://example.com/contracts/vendor-agreement.pdf",
            "filename": "vendor-agreement.pdf"
          }
        }
      ]
    }
  ]
}
```

<Warning>
  استخدم فقط عناوين URL عامة يمكن لـ Venice جلبها دون مصادقة. للملفات الخاصة، أرسل عنوان URL لبيانات base64.
</Warning>

## ملفات متعددة

يمكنك تضمين أكثر من كتلة ملف في نفس الرسالة. ضع تعليمات نصية قصيرة قبل الملفات حتى يعرف النموذج كيفية استخدامها.

```json theme={null}
{
  "model": "openai-gpt-55",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Compare these two policy drafts. Return the material differences and recommend which version is clearer."
        },
        {
          "type": "file",
          "file": {
            "file_data": "data:application/pdf;base64,JVBERi0xLjQK...",
            "filename": "policy-v1.pdf"
          }
        },
        {
          "type": "file",
          "file": {
            "file_data": "data:application/pdf;base64,JVBERi0xLjQK...",
            "filename": "policy-v2.pdf"
          }
        }
      ]
    }
  ]
}
```

للحصول على أفضل النتائج، سمِّ كل ملف بوضوح وأشر إلى تلك الأسماء في prompt الخاص بك.

## عناوين URL للبيانات

للملفات المحلية، رمّز بايتات الملف كـ base64 وضع لها بادئة بنوع MIME الصحيح:

| نوع الملف | بادئة عنوان URL للبيانات                                                                 |
| --------- | ---------------------------------------------------------------------------------------- |
| PDF       | `data:application/pdf;base64,`                                                           |
| DOCX      | `data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,`   |
| PPTX      | `data:application/vnd.openxmlformats-officedocument.presentationml.presentation;base64,` |
| XLSX      | `data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,`         |
| CSV       | `data:text/csv;base64,`                                                                  |
| Markdown  | `data:text/markdown;base64,`                                                             |
| نص عادي   | `data:text/plain;base64,`                                                                |
| JSON      | `data:application/json;base64,`                                                          |

إذا كنت لا تعرف نوع MIME الدقيق، فاستخدم `application/octet-stream`. تضمين `filename` دقيق لا يزال يساعد Venice في تحديد الملف وعرضه.

## العمل مع الملفات الكبيرة

نظرًا لأن الملفات تصبح نص prompt، يمكن أن تزيد الملفات الكبيرة من زمن الاستجابة، واستخدام الـ tokens، والتكلفة. ضع نافذة سياق النموذج في اعتبارك.

يجب أن يكون الملف الخام 25 ميجابايت أو أقل. يزيد ترميز base64 من حجم الطلب بنحو 33%، لذا فإن ملفًا قريبًا من حد 25 ميجابايت سينتج جسم طلب JSON أكبر.

أنماط جيدة للملفات الكبيرة:

* اطلب مهمة محددة بدلًا من prompt واسع "حلل كل شيء".
* قم بتضمين المستندات اللازمة فقط للإجابة الحالية.
* استخدم النماذج ذات `availableContextTokens` الأكبر للتقارير الطويلة أو قواعد الشفرة.
* ضع المستندات المستقرة والمتكررة قبل أسئلة المستخدم الديناميكية إذا كنت تستخدم أيضًا [prompt caching](/guides/features/prompt-caching).
* استخدم `stream: true` عندما تتوقع استجابة طويلة.

## إدخالات الملفات مقابل Text Parser

استخدم إدخالات ملفات الدردشة عندما تريد أن يستنتج النموذج من الملف فورًا.

استخدم [Text Parser API](/api-reference/endpoint/augment/text-parser) عندما تريد استخراج النص أولًا، أو فحص عدد الـ tokens، أو تخزين النص المستخرج في نظامك الخاص، أو إرسال نفس النص المستخرج إلى طلبات متعددة.

| الحاجة                                        | استخدم                                       |
| --------------------------------------------- | -------------------------------------------- |
| اسأل النموذج عن مستند في طلب واحد             | إدخال ملف الدردشة                            |
| استخرج النص دون استدلال النموذج               | Text Parser API                              |
| تحقق من عدد tokens المستخرج قبل الـ prompting | Text Parser API                              |
| أعد استخدام النص المستخرج عبر طلبات متعددة    | Text Parser API، ثم ضمّن النص في الـ prompts |

## أفضل الممارسات

* قم بتضمين `filename` كلما أمكن، خاصة عند إرسال ملفات متعددة.
* ضع التعليمات قبل كتل الملفات حتى يعرف النموذج المهمة قبل قراءة المحتوى المستخرج.
* استخدم عناوين URL العامة فقط للملفات التي يمكن جلبها دون cookies أو ترويسات أو حالة جلسة موقعة.
* فضّل عناوين URL لبيانات base64 للملفات الخاصة أو الملفات المُولَّدة داخل تطبيقك.
* اطرح أسئلة مركزة وحدد تنسيق الإخراج الذي تريده.
* للاستخراج المُهيكَل، اجمع بين إدخالات الملفات و[الاستجابات المُهيكَلة](/guides/features/structured-responses).

## استكشاف الأخطاء وإصلاحها

<AccordionGroup>
  <Accordion title="يقول النموذج إنه لا يمكنه الوصول إلى الملف">
    تأكد من أن محتوى الرسالة يستخدم مصفوفة ويتضمن كتلة `type: "file"`. إذا استخدمت عنوان URL، تحقق من أنه قابل للوصول علنًا دون مصادقة.
  </Accordion>

  <Accordion title="الطلب بطيء أو مكلف">
    قد يستخرج الملف كمية كبيرة من النص. استخدم نموذجًا بسياق أكبر، أو ضيّق المهمة، أو أرسل ملفات أقل، أو استخرج النص مسبقًا وقصره باستخدام Text Parser API.
  </Accordion>

  <Accordion title="تجاهلت الاستجابة أحد ملفاتي">
    أعطِ كل ملف `filename` وصفيًا وأشر إلى أسماء الملفات مباشرة في prompt الخاص بك. على سبيل المثال، "Compare `policy-v1.pdf` against `policy-v2.pdf`."
  </Accordion>

  <Accordion title="يرفض النموذج محتوى الملف">
    تتوفر إدخالات الملفات على نماذج الدردشة المتوافقة. تحقق من [صفحة النماذج](/models/overview) لمعرفة قدرات النماذج الحالية وحدود السياق، أو جرّب نموذج نص حالي بسياق كبير.
  </Accordion>
</AccordionGroup>