الانتقال إلى المحتوى الرئيسي
تتيح لك إدخالات الملفات إرفاق المستندات وملفات المصدر مباشرة بطلب /chat/completions. تستخرج Venice الملف إلى نص قبل إرساله إلى النموذج المحدد، حتى تتمكن من طرح أسئلة، أو التلخيص، أو المقارنة، أو تحويل محتوى الملف دون بناء المحلل اللغوي الخاص بك أولًا. استخدم إدخالات الملفات عندما يعتمد prompt على محتويات مستند أو جدول بيانات أو ملف markdown أو ملف JSON أو ملف شفرة. هذه مدخلات نطاقها الطلب، وليست تخزين ملفات دائم، لذا قم بتضمين الملف في كل طلب يحتاجه.
تستخدم إدخالات الملفات مصفوفة محتوى الدردشة المتوافقة مع OpenAI. أضف كتلة محتوى بـ type: "file" وقدّم محتوى الملف في file.file_data.

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

يقبل 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
يتم استخراج الملفات إلى نص قبل الاستدلال. يحتسب النص المستخرج ضمن سياق إدخال النموذج، لذا اختر نموذجًا بكمية كافية من availableContextTokens للملف بالإضافة إلى تعليماتك والإجابة المتوقعة.

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

أرسل مصفوفة messages حيث يكون content لرسالة المستخدم مصفوفة من كتل النص والملفات: 
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)

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

إذا كان الملف مستضافًا بالفعل على عنوان URL عام لـ HTTP أو HTTPS، فمرر عنوان URL في file_data بدلًا من ترميزه بـ base64: 
{
  "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"
          }
        }
      ]
    }
  ]
}
استخدم فقط عناوين URL عامة يمكن لـ Venice جلبها دون مصادقة. للملفات الخاصة، أرسل عنوان URL لبيانات base64.

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

يمكنك تضمين أكثر من كتلة ملف في نفس الرسالة. ضع تعليمات نصية قصيرة قبل الملفات حتى يعرف النموذج كيفية استخدامها. 
{
  "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 للبيانات
PDFdata:application/pdf;base64,
DOCXdata:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,
PPTXdata:application/vnd.openxmlformats-officedocument.presentationml.presentation;base64,
XLSXdata:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,
CSVdata:text/csv;base64,
Markdowndata:text/markdown;base64,
نص عاديdata:text/plain;base64,
JSONdata:application/json;base64,
إذا كنت لا تعرف نوع MIME الدقيق، فاستخدم application/octet-stream. تضمين filename دقيق لا يزال يساعد Venice في تحديد الملف وعرضه.

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

نظرًا لأن الملفات تصبح نص prompt، يمكن أن تزيد الملفات الكبيرة من زمن الاستجابة، واستخدام الـ tokens، والتكلفة. ضع نافذة سياق النموذج في اعتبارك. يجب أن يكون الملف الخام 25 ميجابايت أو أقل. يزيد ترميز base64 من حجم الطلب بنحو 33%، لذا فإن ملفًا قريبًا من حد 25 ميجابايت سينتج جسم طلب JSON أكبر. أنماط جيدة للملفات الكبيرة:
  • اطلب مهمة محددة بدلًا من prompt واسع “حلل كل شيء”.
  • قم بتضمين المستندات اللازمة فقط للإجابة الحالية.
  • استخدم النماذج ذات availableContextTokens الأكبر للتقارير الطويلة أو قواعد الشفرة.
  • ضع المستندات المستقرة والمتكررة قبل أسئلة المستخدم الديناميكية إذا كنت تستخدم أيضًا prompt caching.
  • استخدم stream: true عندما تتوقع استجابة طويلة.

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

استخدم إدخالات ملفات الدردشة عندما تريد أن يستنتج النموذج من الملف فورًا. استخدم Text Parser API عندما تريد استخراج النص أولًا، أو فحص عدد الـ tokens، أو تخزين النص المستخرج في نظامك الخاص، أو إرسال نفس النص المستخرج إلى طلبات متعددة.
الحاجةاستخدم
اسأل النموذج عن مستند في طلب واحدإدخال ملف الدردشة
استخرج النص دون استدلال النموذجText Parser API
تحقق من عدد tokens المستخرج قبل الـ promptingText Parser API
أعد استخدام النص المستخرج عبر طلبات متعددةText Parser API، ثم ضمّن النص في الـ prompts

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

  • قم بتضمين filename كلما أمكن، خاصة عند إرسال ملفات متعددة.
  • ضع التعليمات قبل كتل الملفات حتى يعرف النموذج المهمة قبل قراءة المحتوى المستخرج.
  • استخدم عناوين URL العامة فقط للملفات التي يمكن جلبها دون cookies أو ترويسات أو حالة جلسة موقعة.
  • فضّل عناوين URL لبيانات base64 للملفات الخاصة أو الملفات المُولَّدة داخل تطبيقك.
  • اطرح أسئلة مركزة وحدد تنسيق الإخراج الذي تريده.
  • للاستخراج المُهيكَل، اجمع بين إدخالات الملفات والاستجابات المُهيكَلة.

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

تأكد من أن محتوى الرسالة يستخدم مصفوفة ويتضمن كتلة type: "file". إذا استخدمت عنوان URL، تحقق من أنه قابل للوصول علنًا دون مصادقة.
قد يستخرج الملف كمية كبيرة من النص. استخدم نموذجًا بسياق أكبر، أو ضيّق المهمة، أو أرسل ملفات أقل، أو استخرج النص مسبقًا وقصره باستخدام Text Parser API.
أعطِ كل ملف filename وصفيًا وأشر إلى أسماء الملفات مباشرة في prompt الخاص بك. على سبيل المثال، “Compare policy-v1.pdf against policy-v2.pdf.”
تتوفر إدخالات الملفات على نماذج الدردشة المتوافقة. تحقق من صفحة النماذج لمعرفة قدرات النماذج الحالية وحدود السياق، أو جرّب نموذج نص حالي بسياق كبير.