Carica file in un'Archiviazione Vettoriale

Carica il contenuto dei file nel Vector Store con operazioni in batch

Esempi di Richieste

cURL

curl -X POST \
  https://api.rememberizer.ai/api/v1/vector-stores/vs_abc123/documents/upload \
  -H "x-api-key: YOUR_API_KEY" \
  -F "files=@/path/to/document1.pdf" \
  -F "files=@/path/to/document2.docx"

Sostituisci YOUR_API_KEY con la tua reale chiave API del Vector Store, vs_abc123 con il tuo ID del Vector Store e fornisci i percorsi ai tuoi file locali.

JavaScript

const uploadFiles = async (vectorStoreId, files) => {
  const formData = new FormData();
  
  // Aggiungi più file ai dati del modulo
  for (const file of files) {
    formData.append('files', file);
  }
  
  const response = await fetch(`https://api.rememberizer.ai/api/v1/vector-stores/${vectorStoreId}/documents/upload`, {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY'
      // Nota: Non impostare l'intestazione Content-Type, verrà impostata automaticamente con il confine corretto
    },
    body: formData
  });
  
  const data = await response.json();
  console.log(data);
};

// Esempio di utilizzo con l'elemento di input file
const fileInput = document.getElementById('fileInput');
uploadFiles('vs_abc123', fileInput.files);

Sostituisci YOUR_API_KEY con la tua reale chiave API del Vector Store e vs_abc123 con il tuo ID del Vector Store.

Python

import requests

def upload_files(vector_store_id, file_paths):
    headers = {
        "x-api-key": "YOUR_API_KEY"
    }
    
    files = [('files', (file_path.split('/')[-1], open(file_path, 'rb'))) for file_path in file_paths]
    
    response = requests.post(
        f"https://api.rememberizer.ai/api/v1/vector-stores/{vector_store_id}/documents/upload",
        headers=headers,
        files=files
    )
    
    data = response.json()
    print(data)

upload_files('vs_abc123', ['/path/to/document1.pdf', '/path/to/document2.docx'])

Sostituisci YOUR_API_KEY con la tua reale chiave API del Vector Store, vs_abc123 con il tuo ID del Vector Store e fornisci i percorsi ai tuoi file locali.

Ruby

require 'net/http'
require 'uri'
require 'json'

def upload_files(vector_store_id, file_paths)
  uri = URI("https://api.rememberizer.ai/api/v1/vector-stores/#{vector_store_id}/documents/upload")
  
  # Crea un nuovo oggetto HTTP
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  
  # Crea una richiesta multipart-form
  request = Net::HTTP::Post.new(uri)
  request['x-api-key'] = 'YOUR_API_KEY'
  
  # Crea un confine multipart
  boundary = "RubyFormBoundary#{rand(1000000)}"
  request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
  
  # Costruisci il corpo della richiesta
  body = []
  file_paths.each do |file_path|
    file_name = File.basename(file_path)
    file_content = File.read(file_path, mode: 'rb')
    
    body << "--#{boundary}\r\n"
    body << "Content-Disposition: form-data; name=\"files\"; filename=\"#{file_name}\"\r\n"
    body << "Content-Type: #{get_content_type(file_name)}\r\n\r\n"
    body << file_content
    body << "\r\n"
  end
  body << "--#{boundary}--\r\n"
  
  request.body = body.join
  
  # Invia la richiesta
  response = http.request(request)
  
  # Analizza e restituisci la risposta
  JSON.parse(response.body)
end

Metodo di aiuto per determinare il tipo di contenuto

def get_content_type(filename) ext = File.extname(filename).downcase case ext when '.pdf' then 'application/pdf' when '.doc' then 'application/msword' when '.docx' then 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' when '.txt' then 'text/plain' when '.md' then 'text/markdown' when '.json' then 'application/json' else 'application/octet-stream' end end

Esempio di utilizzo

result = upload_files('vs_abc123', ['/path/to/document1.pdf', '/path/to/document2.docx']) puts result

<div data-gb-custom-block data-tag="hint" data-style='info'>

Sostituisci `YOUR_API_KEY` con la tua chiave API effettiva del Vector Store, `vs_abc123` con il tuo ID del Vector Store e fornisci i percorsi ai tuoi file locali.

</div>

</div>

</div>

## Parametri del percorso

| Parametro          | Tipo   | Descrizione                                                        |
|--------------------|--------|--------------------------------------------------------------------|
| vector-store-id    | string | **Obbligatorio.** L'ID del vector store a cui caricare i file.    |

## Corpo della Richiesta

Questo endpoint accetta una richiesta `multipart/form-data` con uno o più file nel campo `files`.

## Formato di Risposta

```json
{
  "documents": [
    {
      "id": 1234,
      "name": "document1.pdf",
      "type": "application/pdf",
      "size": 250000,
      "status": "processing",
      "created": "2023-06-15T10:15:00Z",
      "vector_store": "vs_abc123"
    },
    {
      "id": 1235,
      "name": "document2.docx",
      "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "size": 180000,
      "status": "processing",
      "created": "2023-06-15T10:15:00Z",
      "vector_store": "vs_abc123"
    }
  ],
  "errors": []
}

Se alcuni file non riescono a essere caricati, verranno elencati nell'array errors:

{
  "documents": [
    {
      "id": 1234,
      "name": "document1.pdf",
      "type": "application/pdf",
      "size": 250000,
      "status": "processing",
      "created": "2023-06-15T10:15:00Z",
      "vector_store": "vs_abc123"
    }
  ],
  "errors": [
    {
      "file": "document2.docx",
      "error": "Formato file non supportato"
    }
  ]
}

Autenticazione

Questo endpoint richiede autenticazione utilizzando una chiave API nell'intestazione x-api-key.

Formati di File Supportati

• PDF (.pdf)

• Microsoft Word (.doc, .docx)

• Microsoft Excel (.xls, .xlsx)

• Microsoft PowerPoint (.ppt, .pptx)

• File di testo (.txt)

• Markdown (.md)

• JSON (.json)

• HTML (.html, .htm)

Limiti di Dimensione dei File

• Limite di dimensione per file singolo: 50MB

• Limite di dimensione totale della richiesta: 100MB

• Numero massimo di file per richiesta: 20

Risposte di Errore

Codice di Stato	Descrizione
400	Richiesta Errata - Nessun file fornito o formato di richiesta non valido
401	Non Autorizzato - Chiave API non valida o mancante
404	Non Trovato - Negozio Vettoriale non trovato
413	Carico Troppo Grande - I file superano il limite di dimensione
415	Tipo di Media Non Supportato - Formato file non supportato
500	Errore Interno del Server
207	Multi-Status - Alcuni file sono stati caricati con successo, ma altri hanno fallito

Stato di Elaborazione

I file vengono inizialmente accettati con uno stato di processing. Puoi controllare lo stato di elaborazione dei documenti utilizzando l'endpoint Get a List of Documents in a Vector Store. Lo stato finale sarà uno dei seguenti:

• done: Il documento è stato elaborato con successo

• error: Si è verificato un errore durante l'elaborazione

• processing: Il documento è ancora in fase di elaborazione

Il tempo di elaborazione dipende dalle dimensioni e dalla complessità del file. Il tempo di elaborazione tipico è compreso tra 30 secondi e 5 minuti per documento.

Operazioni in Batch

Per caricare in modo efficiente più file nel tuo Vector Store, Rememberizer supporta operazioni in batch. Questo approccio aiuta a ottimizzare le prestazioni quando si gestiscono grandi quantità di documenti.

Implementazione del Caricamento Batch

Python

import os
import requests
import time
import concurrent.futures
from pathlib import Path

def batch_upload_to_vector_store(vector_store_id, folder_path, batch_size=5, file_types=None):
    """
    Carica tutti i file da una directory in uno Store di Vettori in batch
    
    Args:
        vector_store_id: ID dello store di vettori
        folder_path: Percorso della cartella contenente i file da caricare
        batch_size: Numero di file da caricare in ciascun batch
        file_types: Lista opzionale di estensioni di file da filtrare (es. ['.pdf', '.docx'])
        
    Returns:
        Lista dei risultati del caricamento
    """
    api_key = "YOUR_API_KEY"
    headers = {"x-api-key": api_key}
    
    # Ottieni la lista dei file nella directory
    files = []
    for entry in os.scandir(folder_path):
        if entry.is_file():
            file_path = Path(entry.path)
            # Filtra per estensione di file se specificato
            if file_types is None or file_path.suffix.lower() in file_types:
                files.append(file_path)
    
    print(f"Trovati {len(files)} file da caricare")
    results = []
    
    # Elabora i file in batch
    for i in range(0, len(files), batch_size):
        batch = files[i:i+batch_size]
        print(f"Elaborazione del batch {i//batch_size + 1}/{(len(files) + batch_size - 1)//batch_size}: {len(batch)} file")
        
        # Carica il batch
        upload_files = []
        for file_path in batch:
            upload_files.append(('files', (file_path.name, open(file_path, 'rb'))))
        
        try:
            response = requests.post(
                f"https://api.rememberizer.ai/api/v1/vector-stores/{vector_store_id}/documents/upload",
                headers=headers,
                files=upload_files
            )
            
            # Chiudi tutti i gestori di file
            for _, (_, file_obj) in upload_files:
                file_obj.close()
            
            if response.status_code in (200, 201, 207):
                batch_result = response.json()
                results.append(batch_result)
                print(f"Caricamento del batch riuscito - {len(batch_result.get('documents', []))} documenti elaborati")
                
                # Controlla per errori
                if batch_result.get('errors') and len(batch_result['errors']) > 0:
                    print(f"Errori riscontrati: {len(batch_result['errors'])}")
                    for error in batch_result['errors']:
                        print(f"- {error['file']}: {error['error']}")
            else:
                print(f"Caricamento del batch fallito con codice di stato {response.status_code}: {response.text}")
                results.append({"error": f"Batch fallito: {response.text}"})
                
        except Exception as e:
            print(f"Eccezione durante il caricamento del batch: {str(e)}")
            results.append({"error": str(e)})
            
            # Chiudi eventuali gestori di file rimanenti in caso di eccezione
            for _, (_, file_obj) in upload_files:
                try:
                    file_obj.close()
                except:
                    pass
        
        # Limitazione della velocità - pausa tra i batch
        if i + batch_size < len(files):
            print("Pausa prima del prossimo batch...")
            time.sleep(2)
    
    return results

# Esempio di utilizzo
results = batch_upload_to_vector_store(
    'vs_abc123',
    '/path/to/documents/folder',
    batch_size=5,
    file_types=['.pdf', '.docx', '.txt']
)

JavaScript

/**
 * Carica file in un Vector Store in batch
 * 
 * @param {string} vectorStoreId - ID del Vector Store
 * @param {FileList|File[]} files - File da caricare
 * @param {Object} options - Opzioni di configurazione
 * @returns {Promise<Array>} - Elenco dei risultati del caricamento
 */
async function batchUploadToVectorStore(vectorStoreId, files, options = {}) {
  const {
    batchSize = 5,
    delayBetweenBatches = 2000,
    onProgress = null
  } = options;
  
  const apiKey = 'YOUR_API_KEY';
  const results = [];
  const fileList = Array.from(files);
  const totalBatches = Math.ceil(fileList.length / batchSize);
  
  console.log(`Preparazione per caricare ${fileList.length} file in ${totalBatches} batch`);
  
  // Elabora i file in batch
  for (let i = 0; i < fileList.length; i += batchSize) {
    const batch = fileList.slice(i, i + batchSize);
    const batchNumber = Math.floor(i / batchSize) + 1;
    
    console.log(`Elaborazione batch ${batchNumber}/${totalBatches}: ${batch.length} file`);
    
    if (onProgress) {
      onProgress({
        currentBatch: batchNumber,
        totalBatches: totalBatches,
        filesInBatch: batch.length,
        totalFiles: fileList.length,
        completedFiles: i
      });
    }
    
    // Crea FormData per questo batch
    const formData = new FormData();
    batch.forEach(file => {
      formData.append('files', file);
    });
    
    try {
      const response = await fetch(
        `https://api.rememberizer.ai/api/v1/vector-stores/${vectorStoreId}/documents/upload`,
        {
          method: 'POST',
          headers: {
            'x-api-key': apiKey
          },
          body: formData
        }
      );
      
      if (response.ok) {
        const batchResult = await response.json();
        results.push(batchResult);
        
        console.log(`Batch caricato con successo - ${batchResult.documents?.length || 0} documenti elaborati`);
        
        // Controlla gli errori
        if (batchResult.errors && batchResult.errors.length > 0) {
          console.warn(`Errori riscontrati: ${batchResult.errors.length}`);
          batchResult.errors.forEach(error => {
            console.warn(`- ${error.file}: ${error.error}`);
          });
        }
      } else {
        console.error(`Il caricamento del batch è fallito con stato ${response.status}: ${await response.text()}`);
        results.push({ error: `Il batch è fallito con stato: ${response.status}` });
      }
    } catch (error) {
      console.error(`Eccezione durante il caricamento del batch: ${error.message}`);
      results.push({ error: error.message });
    }
    
    // Aggiungi un ritardo tra i batch per evitare limitazioni di velocità
    if (i + batchSize < fileList.length) {
      console.log(`In pausa per ${delayBetweenBatches}ms prima del prossimo batch...`);
      await new Promise(resolve => setTimeout(resolve, delayBetweenBatches));
    }
  }
  
  console.log(`Caricamento completato. Elaborati ${fileList.length} file.`);
  return results;
}

// Esempio di utilizzo con elemento di input file
document.getElementById('upload-button').addEventListener('click', async () => {
  const fileInput = document.getElementById('file-input');
  const vectorStoreId = 'vs_abc123';
  
  const progressBar = document.getElementById('progress-bar');
  
  try {
    const results = await batchUploadToVectorStore(vectorStoreId, fileInput.files, {
      batchSize: 5,
      onProgress: (progress) => {
        // Aggiorna l'interfaccia utente di avanzamento
        const percentage = Math.round((progress.completedFiles / progress.totalFiles) * 100);
        progressBar.style.width = `${percentage}%`;
        progressBar.textContent = `${percentage}% (Batch ${progress.currentBatch}/${progress.totalBatches})`;
      }
    });
    
    console.log('Risultati del caricamento completati:', results);
  } catch (error) {
    console.error('Caricamento fallito:', error);
  }
});

Ruby

require 'net/http'
require 'uri'
require 'json'
require 'mime/types'

# Carica file in un Vector Store in batch
#
# @param vector_store_id [String] ID del Vector Store
# @param folder_path [String] Percorso della cartella contenente i file da caricare
# @param batch_size [Integer] Numero di file da caricare in ogni batch
# @param file_types [Array<String>] Array opzionale di estensioni di file da filtrare
# @param delay_between_batches [Float] Secondi da attendere tra i batch
# @return [Array] Elenco dei risultati di upload
def batch_upload_to_vector_store(vector_store_id, folder_path, batch_size: 5, file_types: nil, delay_between_batches: 2.0)
  api_key = 'YOUR_API_KEY'
  results = []
  
  # Ottieni l'elenco dei file nella directory
  files = Dir.entries(folder_path)
    .select { |f| File.file?(File.join(folder_path, f)) }
    .select { |f| file_types.nil? || file_types.include?(File.extname(f).downcase) }
    .map { |f| File.join(folder_path, f) }
  
  puts "Trovati #{files.count} file da caricare"
  total_batches = (files.count.to_f / batch_size).ceil
  
  # Elabora i file in lotti
  files.each_slice(batch_size).with_index do |batch, batch_index|
    puts "Elaborazione del lotto #{batch_index + 1}/#{total_batches}: #{batch.count} file"
    
    # Prepara la richiesta HTTP
    uri = URI("https://api.rememberizer.ai/api/v1/vector-stores/#{vector_store_id}/documents/upload")
    request = Net::HTTP::Post.new(uri)
    request['x-api-key'] = api_key
    
    # Crea un confine del modulo multipart
    boundary = "RubyBoundary#{rand(1000000)}"
    request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
    
    # Costruisci il corpo della richiesta
    body = []
    batch.each do |file_path|
      file_name = File.basename(file_path)
      mime_type = MIME::Types.type_for(file_path).first&.content_type || 'application/octet-stream'
      
      begin
        file_content = File.binread(file_path)
        
        body << "--#{boundary}\r\n"
        body << "Content-Disposition: form-data; name=\"files\"; filename=\"#{file_name}\"\r\n"
        body << "Content-Type: #{mime_type}\r\n\r\n"
        body << file_content
        body << "\r\n"
      rescue => e
        puts "Errore nella lettura del file #{file_path}: #{e.message}"
      end
    end
    body << "--#{boundary}--\r\n"
    
    request.body = body.join
    
    # Invia la richiesta
    begin
      http = Net::HTTP.new(uri.host, uri.port)
      http.use_ssl = true
      response = http.request(request)
      
      if response.code.to_i == 200 || response.code.to_i == 201 || response.code.to_i == 207
        batch_result = JSON.parse(response.body)
        results << batch_result
        
        puts "Lotto caricato con successo - #{batch_result['documents']&.count || 0} documenti elaborati"
        
        # Controlla gli errori
        if batch_result['errors'] && !batch_result['errors'].empty?
          puts "Errori riscontrati: #{batch_result['errors'].count}"
          batch_result['errors'].each do |error|
            puts "- #{error['file']}: #{error['error']}"
          end
        end
      else
        puts "Caricamento del lotto fallito con codice di stato #{response.code}: #{response.body}"
        results << { "error" => "Lotto fallito: #{response.body}" }
      end
    rescue => e
      puts "Eccezione durante il caricamento del lotto: #{e.message}"
      results << { "error" => e.message }
    end
    
    # Limitazione della velocità - pausa tra i lotti
    if batch_index < total_batches - 1
      puts "Pausa di #{delay_between_batches} secondi prima del prossimo lotto..."
      sleep(delay_between_batches)
    end
  end
  
  puts "Caricamento completato. Elaborati #{files.count} file."
  results
end

# Esempio di utilizzo
results = batch_upload_to_vector_store(
  'vs_abc123',
  '/path/to/documents/folder',
  batch_size: 5,
  file_types: ['.pdf', '.docx', '.txt'],
  delay_between_batches: 2.0
)

Migliori Pratiche per il Caricamento Batch

Per ottimizzare le prestazioni e l'affidabilità durante il caricamento di grandi volumi di file:

1. Gestire la Dimensione del Batch: Mantieni le dimensioni del batch tra 5-10 file per prestazioni ottimali. Troppi file in una singola richiesta aumentano il rischio di timeout.

2. Implementare il Rate Limiting: Aggiungi ritardi tra i batch (2-3 secondi raccomandati) per evitare di superare i limiti di velocità dell'API.

3. Aggiungere Logica di Riprova per Errori: Per i sistemi di produzione, implementa una logica di riprova per i caricamenti non riusciti con backoff esponenziale.

4. Validare i Tipi di File: Pre-filtra i file per garantire che siano tipi supportati prima di tentare il caricamento.

5. Monitorare il Progresso del Batch: Per le applicazioni rivolte agli utenti, fornisci feedback sul progresso delle operazioni batch.

6. Gestire il Successo Parziale: L'API può restituire un codice di stato 207 per il successo parziale. Controlla sempre gli stati dei singoli documenti.

7. Pulire le Risorse: Assicurati che tutti i gestori di file siano chiusi correttamente, specialmente quando si verificano errori.

8. Parallelizzare con Saggezza: Per caricamenti molto grandi (migliaia di file), considera più processi batch concorrenti che mirano a diversi store di vettori, quindi combina i risultati in seguito se necessario.

9. Implementare i Checksum: Per dati critici, verifica l'integrità del file prima e dopo il caricamento con i checksum.

10. Registrare Risultati Completi: Mantieni registri dettagliati di tutte le operazioni di caricamento per la risoluzione dei problemi.

Seguendo queste migliori pratiche, puoi gestire in modo efficiente l'ingestione di documenti su larga scala nei tuoi store di vettori.