Vai al contenuto principale
I file inputs ti permettono di allegare documenti e file sorgente direttamente a una richiesta /chat/completions. Venice estrae il file in testo prima di inviarlo al modello selezionato, quindi puoi porre domande, riassumere, confrontare o trasformare il contenuto del file senza prima costruire il tuo parser. Usa i file inputs quando il tuo prompt dipende dal contenuto di un documento, foglio di calcolo, file markdown, file JSON o file di codice. Sono input legati alla richiesta, non storage persistente di file, quindi includi il file in ogni richiesta che ne ha bisogno.
I file inputs usano l’array di contenuto chat compatibile con OpenAI. Aggiungi un blocco di contenuto con type: "file" e fornisci il contenuto del file in file.file_data.

​
Tipi di file supportati

L’API chat accetta i file inputs sia come data URL base64 sia come URL pubblicamente accessibili. La dimensione massima del file è di 25MB per file, misurata dopo la decodifica di un data URL base64 o dopo il fetch di un URL.
CategoriaFormati
DocumentiPDF, DOCX, PPTX
Fogli di calcoloXLSX, XLS, CSV
Testo e datiTXT, Markdown, JSON
Codice sorgenteLa maggior parte dei file di codice comuni, inclusi .py, .js, .ts, .c, .cpp, .java, .go, .rs, .ps1, .sh, .yaml e .sql
I file vengono estratti in testo prima dell’inferenza. Il testo estratto conta verso il contesto di input del modello, quindi scegli un modello con availableContextTokens sufficienti per il file più le tue istruzioni e la risposta attesa.

​
Utilizzo di base

Invia un array messages in cui il content del messaggio user è un array di blocchi di testo e di file: 
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 di file

Se il file è già ospitato a un URL HTTP o HTTPS pubblico, passa l’URL in file_data invece di codificarlo in 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"
          }
        }
      ]
    }
  ]
}
Usa solo URL pubblici che Venice possa recuperare senza autenticazione. Per file privati, invia un data URL base64.

​
File multipli

Puoi includere più di un blocco di file nello stesso messaggio. Metti una breve istruzione testuale prima dei file in modo che il modello sappia come utilizzarli. 
{
  "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"
          }
        }
      ]
    }
  ]
}
Per risultati ottimali, dai un nome chiaro a ciascun file e fai riferimento a quei nomi nel tuo prompt.

​
Data URL

Per i file locali, codifica i byte del file in base64 e anteponi il MIME type corretto:
Tipo di filePrefisso del data 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,
Plain textdata:text/plain;base64,
JSONdata:application/json;base64,
Se non conosci il MIME type esatto, usa application/octet-stream. Includere un filename accurato aiuta comunque Venice a identificare e visualizzare il file.

​
Lavorare con file di grandi dimensioni

Poiché i file diventano testo del prompt, i file grandi possono aumentare latenza, utilizzo di token e costi. Tieni a mente la finestra di contesto del modello. Il file raw deve essere di 25MB o meno. La codifica base64 aumenta la dimensione della richiesta di circa il 33%, quindi un file vicino al limite di 25MB produrrà un corpo JSON di richiesta più grande. Buoni pattern per file di grandi dimensioni:
  • Chiedi un compito specifico invece di un prompt generico “analizza tutto”.
  • Includi solo i documenti necessari per la risposta corrente.
  • Usa modelli con availableContextTokens più ampi per report o codebase lunghi.
  • Metti i documenti stabili e ripetuti prima delle domande dinamiche dell’utente se stai usando anche il prompt caching.
  • Usa stream: true quando ti aspetti una risposta lunga.

​
File inputs vs. Text Parser

Usa i file inputs della chat quando vuoi che il modello ragioni immediatamente sul file. Usa l’API Text Parser quando vuoi prima estrarre il testo, ispezionare il conteggio dei token, memorizzare il testo estratto nel tuo sistema o inviare lo stesso testo estratto a più richieste.
NecessitàUsa
Chiedere a un modello informazioni su un documento in una sola richiestaFile input chat
Estrarre testo senza inferenza del modelloAPI Text Parser
Controllare il conteggio dei token estratti prima del promptAPI Text Parser
Riutilizzare il testo estratto in molte richiesteAPI Text Parser, quindi includi il testo nei prompt

​
Best practice

  • Includi filename quando possibile, specialmente quando invii più file.
  • Metti l’istruzione prima dei blocchi di file in modo che il modello conosca il compito prima di leggere il contenuto estratto.
  • Usa URL pubblici solo per file che possono essere recuperati senza cookie, header o stato di sessione firmato.
  • Preferisci data URL base64 per file privati o file generati all’interno della tua applicazione.
  • Fai domande mirate e specifica il formato di output che desideri.
  • Per estrazioni strutturate, combina i file inputs con le risposte strutturate.

​
Risoluzione problemi

Assicurati che il content del messaggio usi un array e includa un blocco type: "file". Se hai usato un URL, verifica che sia raggiungibile pubblicamente senza autenticazione.
Il file potrebbe estrarsi in una grande quantità di testo. Usa un modello con contesto più ampio, restringi il compito, invia meno file o pre-estrai e taglia il testo con l’API Text Parser.
Assegna a ciascun file un filename descrittivo e fai riferimento ai filename direttamente nel tuo prompt. Ad esempio, “Compare policy-v1.pdf against policy-v2.pdf.”
I file inputs sono disponibili su modelli chat compatibili. Controlla la pagina Modelli per le capacità correnti del modello e i limiti di contesto, o prova un modello di testo recente con contesto ampio.