# Cerca documenti dell'Archivio Vettoriale per somiglianza semantica

{% openapi src="/files/TgprWtaxn0x1jf4BJIMN" path="/vector-stores/{vector-store-id}/documents/search" method="get" %}
[rememberizer\_openapi.yml](https://2549770777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F57qWu8jBt3M3SWmz6Y83%2Fuploads%2Fgit-blob-4f45581f68048634d677b5e3d260a677eeb0242f%2Frememberizer_openapi.yml?alt=media\&token=7f673453-89b5-4d08-beab-3fb44863de41)
{% endopenapi %}

## Esempi di Richieste

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET \
  "https://api.rememberizer.ai/api/v1/vector-stores/vs_abc123/documents/search?q=Come%20integrare%20il%20nostro%20prodotto%20con%20sistemi%20di%20terze%20parti&n=5&prev_chunks=1&next_chunks=1" \
  -H "x-api-key: YOUR_API_KEY"
```

{% hint style="info" %}
Sostituisci `YOUR_API_KEY` con la tua reale chiave API del Vector Store e `vs_abc123` con il tuo ID del Vector Store.
{% endhint %}
{% endtab %}

{% tab title="JavaScript" %}

```javascript
const searchVectorStore = async (vectorStoreId, query, numResults = 5, prevChunks = 1, nextChunks = 1) => {
  const url = new URL(`https://api.rememberizer.ai/api/v1/vector-stores/${vectorStoreId}/documents/search`);
  url.searchParams.append('q', query);
  url.searchParams.append('n', numResults);
  url.searchParams.append('prev_chunks', prevChunks);
  url.searchParams.append('next_chunks', nextChunks);
  
  const response = await fetch(url.toString(), {
    method: 'GET',
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  });
  
  const data = await response.json();
  console.log(data);
};

searchVectorStore(
  'vs_abc123',
  'Come integrare il nostro prodotto con sistemi di terze parti',
  5,
  1,
  1
);
```

{% hint style="info" %}
Sostituisci `YOUR_API_KEY` con la tua reale chiave API del Vector Store e `vs_abc123` con il tuo ID del Vector Store.
{% endhint %}
{% endtab %}

{% tab title="Python" %}

```python
import requests

def search_vector_store(vector_store_id, query, num_results=5, prev_chunks=1, next_chunks=1):
    headers = {
        "x-api-key": "YOUR_API_KEY"
    }
    
    params = {
        "q": query,
        "n": num_results,
        "prev_chunks": prev_chunks,
        "next_chunks": next_chunks
    }
    
    response = requests.get(
        f"https://api.rememberizer.ai/api/v1/vector-stores/{vector_store_id}/documents/search",
        headers=headers,
        params=params
    )
    
    data = response.json()
    print(data)

search_vector_store(
    'vs_abc123',
    'Come integrare il nostro prodotto con sistemi di terze parti',
    5,
    1,
    1
)
```

{% hint style="info" %}
Sostituisci `YOUR_API_KEY` con la tua reale chiave API del Vector Store e `vs_abc123` con il tuo ID del Vector Store.
{% endhint %}
{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'net/http'
require 'uri'
require 'json'

def search_vector_store(vector_store_id, query, num_results=5, prev_chunks=1, next_chunks=1)
  uri = URI("https://api.rememberizer.ai/api/v1/vector-stores/#{vector_store_id}/documents/search")
  params = {
    q: query,
    n: num_results,
    prev_chunks: prev_chunks,
    next_chunks: next_chunks
  }
  
  uri.query = URI.encode_www_form(params)
  
  request = Net::HTTP::Get.new(uri)
  request['x-api-key'] = 'YOUR_API_KEY'
  
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  
  response = http.request(request)
  data = JSON.parse(response.body)
  puts data
end

search_vector_store(
  'vs_abc123',
  'Come integrare il nostro prodotto con sistemi di terze parti',
  5,
  1,
  1
)
```

{% hint style="info" %}
Sostituisci `YOUR_API_KEY` con la tua reale chiave API del Vector Store e `vs_abc123` con il tuo ID del Vector Store.
{% endhint %}
{% endtab %}
{% endtabs %}

## Parametri del percorso

| Parametro       | Tipo   | Descrizione                                                   |
| --------------- | ------ | ------------------------------------------------------------- |
| vector-store-id | string | **Obbligatorio.** L'ID del negozio di vettori in cui cercare. |

## Parametri di Query

| Parametro    | Tipo    | Descrizione                                                                  |
| ------------ | ------- | ---------------------------------------------------------------------------- |
| q            | string  | **Obbligatorio.** Il testo della query di ricerca.                           |
| n            | integer | Numero di risultati da restituire. Predefinito: 10.                          |
| t            | number  | Soglia di corrispondenza. Predefinito: 0.7.                                  |
| prev\_chunks | integer | Numero di chunk prima del chunk corrispondente da includere. Predefinito: 0. |
| next\_chunks | integer | Numero di chunk dopo il chunk corrispondente da includere. Predefinito: 0.   |

## Formato di Risposta

```json
{
  "vector_store": {
    "id": "vs_abc123",
    "name": "Documentazione del Prodotto"
  },
  "matched_chunks": [
    {
      "document": {
        "id": 1234,
        "name": "Guida all'Integrazione.pdf",
        "type": "application/pdf",
        "size": 250000,
        "indexed_on": "2023-06-15T10:30:00Z",
        "vector_store": "vs_abc123",
        "created": "2023-06-15T10:15:00Z",
        "modified": "2023-06-15T10:30:00Z"
      },
      "matched_content": "Il nostro prodotto offre diverse opzioni di integrazione per sistemi di terze parti. Il metodo principale è attraverso la nostra API RESTful, che supporta l'autenticazione OAuth2. Inoltre, puoi utilizzare il nostro SDK disponibile in Python, JavaScript e Java.",
      "distance": 0.123
    },
    // ... più chunk corrispondenti
  ]
}
```

## Autenticazione

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

## Risposte di Errore

| Codice di Stato | Descrizione                                                          |
| --------------- | -------------------------------------------------------------------- |
| 400             | Richiesta Errata - Parametri richiesti mancanti o formato non valido |
| 401             | Non Autorizzato - Chiave API non valida o mancante                   |
| 404             | Non Trovato - Negozio di Vettori non trovato                         |
| 500             | Errore Interno del Server                                            |

## Suggerimenti per l'Ottimizzazione della Ricerca

### Finestre di Contesto

Utilizza i parametri `prev_chunks` e `next_chunks` per controllare quanto contesto è incluso con ogni corrispondenza:

* Imposta entrambi a 0 per corrispondenze precise senza contesto
* Imposta entrambi a 1-2 per corrispondenze con contesto minimo
* Imposta entrambi a 3-5 per corrispondenze con contesto sostanziale

### Soglia di Corrispondenza

Il parametro `t` controlla quanto rigorosamente vengono filtrate le corrispondenze:

* Valori più alti (ad es., 0.9) restituiscono solo corrispondenze molto vicine
* Valori più bassi (ad es., 0.5) restituiscono più corrispondenze con maggiore varietà
* Il valore predefinito (0.7) fornisce un approccio equilibrato

## Operazioni in Batch

Per applicazioni ad alta capacità, Rememberizer supporta operazioni in batch efficienti sui vettori di archiviazione. Questi metodi ottimizzano le prestazioni durante l'elaborazione di più query di ricerca.

### Implementazione della Ricerca in Batch

{% tabs %}
{% tab title="Python" %}

```python
import requests
import time
import concurrent.futures

def batch_search_vector_store(vector_store_id, queries, num_results=5, batch_size=10):
    """
    Esegui ricerche in batch su un archivio vettoriale
    
    Args:
        vector_store_id: ID dell'archivio vettoriale da cercare
        queries: Elenco delle stringhe di query di ricerca
        num_results: Numero di risultati per query
        batch_size: Numero di richieste parallele
        
    Returns:
        Elenco dei risultati della ricerca
    """
    headers = {
        "x-api-key": "YOUR_API_KEY"
    }
    
    results = []
    
    # Elabora in batch per evitare di sovraccaricare l'API
    for i in range(0, len(queries), batch_size):
        batch_queries = queries[i:i+batch_size]
        
        with concurrent.futures.ThreadPoolExecutor(max_workers=batch_size) as executor:
            futures = []
            
            for query in batch_queries:
                params = {
                    "q": query,
                    "n": num_results,
                    "prev_chunks": 1,
                    "next_chunks": 1
                }
                
                # Invia la richiesta al pool di thread
                future = executor.submit(
                    requests.get,
                    f"https://api.rememberizer.ai/api/v1/vector-stores/{vector_store_id}/documents/search",
                    headers=headers,
                    params=params
                )
                futures.append(future)
            
            # Raccogli i risultati da tutti i futures
            for future in futures:
                response = future.result()
                if response.status_code == 200:
                    results.append(response.json())
                else:
                    results.append({"error": f"Fallito con codice di stato: {response.status_code}"})
        
        # Aggiungi un ritardo tra i batch per evitare limitazioni di frequenza
        if i + batch_size < len(queries):
            time.sleep(1)
    
    return results

# Esempio di utilizzo
queries = [
    "Integrazione con le API REST",
    "Protocolli di autenticazione",
    "Come distribuire in produzione",
    "Tecniche di ottimizzazione delle prestazioni",
    "Migliori pratiche per la gestione degli errori"
]

search_results = batch_search_vector_store("vs_abc123", queries, num_results=3, batch_size=5)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
/**
 * Esegui ricerche in batch contro un archivio vettoriale
 * 
 * @param {string} vectorStoreId - ID dell'archivio vettoriale
 * @param {string[]} queries - Elenco delle query di ricerca
 * @param {Object} options - Opzioni di configurazione
 * @returns {Promise<Array>} - Elenco dei risultati della ricerca
 */
async function batchSearchVectorStore(vectorStoreId, queries, options = {}) {
  const {
    numResults = 5,
    batchSize = 10,
    delayBetweenBatches = 1000,
    prevChunks = 1,
    nextChunks = 1,
    distanceThreshold = 0.7
  } = options;
  
  const results = [];
  const apiKey = 'YOUR_API_KEY';
  
  // Elabora in batch per gestire il carico dell'API
  for (let i = 0; i < queries.length; i += batchSize) {
    const batchQueries = queries.slice(i, i + batchSize);
    
    // Crea un array di promesse per richieste parallele
    const batchPromises = batchQueries.map(query => {
      const url = new URL(`https://api.rememberizer.ai/api/v1/vector-stores/${vectorStoreId}/documents/search`);
      url.searchParams.append('q', query);
      url.searchParams.append('n', numResults);
      url.searchParams.append('prev_chunks', prevChunks);
      url.searchParams.append('next_chunks', nextChunks);
      url.searchParams.append('t', distanceThreshold);
      
      return fetch(url.toString(), {
        method: 'GET',
        headers: {
          'x-api-key': apiKey
        }
      })
      .then(response => {
        if (response.ok) {
          return response.json();
        } else {
          return { error: `Fallito con stato: ${response.status}` };
        }
      })
      .catch(error => {
        return { error: error.message };
      });
    });
    
    // Aspetta che tutte le richieste nel batch siano completate
    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
    
    // Aggiungi un ritardo tra i batch per evitare il limite di frequenza
    if (i + batchSize < queries.length) {
      await new Promise(resolve => setTimeout(resolve, delayBetweenBatches));
    }
  }
  
  return results;
}

// Esempio di utilizzo
const queries = [
  "Integrazione con le API REST",
  "Protocolli di autenticazione",
  "Come distribuire in produzione",
  "Tecniche di ottimizzazione delle prestazioni",
  "Migliori pratiche per la gestione degli errori"
];

const options = {
  numResults: 3,
  batchSize: 5,
  delayBetweenBatches: 1000,
  prevChunks: 1,
  nextChunks: 1
};

batchSearchVectorStore("vs_abc123", queries, options)
  .then(results => console.log(results))
  .catch(error => console.error("La ricerca in batch è fallita:", error));
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'net/http'
require 'uri'
require 'json'
require 'concurrent'

# Esegui ricerche in batch contro un archivio vettoriale
#
# @param vector_store_id [String] ID del negozio di vettori
# @param queries [Array<String>] Elenco delle query di ricerca
# @param num_results [Integer] Numero di risultati per query
# @param batch_size [Integer] Numero di richieste parallele
# @param delay_between_batches [Float] Secondi da attendere tra i batch
# @return [Array] Risultati della ricerca per ogni query
def batch_search_vector_store(vector_store_id, queries, num_results: 5, batch_size: 10, delay_between_batches: 1.0)
  results = []
  api_key = 'YOUR_API_KEY'
  
  # Elaborare in batch
  queries.each_slice(batch_size).with_index do |batch_queries, batch_index|
    # Creare un pool di thread per l'esecuzione concorrente
    pool = Concurrent::FixedThreadPool.new(batch_size)
    futures = []
    
    batch_queries.each do |query|
      # Inviare ogni richiesta al pool di thread
      futures << Concurrent::Future.execute(executor: pool) do
        uri = URI("https://api.rememberizer.ai/api/v1/vector-stores/#{vector_store_id}/documents/search")
        params = {
          q: query,
          n: num_results,
          prev_chunks: 1,
          next_chunks: 1
        }
        
        uri.query = URI.encode_www_form(params)
        
        request = Net::HTTP::Get.new(uri)
        request['x-api-key'] = api_key
        
        http = Net::HTTP.new(uri.host, uri.port)
        http.use_ssl = true
        
        begin
          response = http.request(request)
          
          if response.code.to_i == 200
            JSON.parse(response.body)
          else
            { "error" => "Fallito con codice di stato: #{response.code}" }
          end
        rescue => e
          { "error" => e.message }
        end
      end
    end
    
    # Raccogliere i risultati da tutti i futures
    batch_results = futures.map(&:value)
    results.concat(batch_results)
    
    # Aggiungere un ritardo tra i batch
    if batch_index < (queries.length / batch_size.to_f).ceil - 1
      sleep(delay_between_batches)
    end
  end
  
  pool.shutdown
  results
end

# Esempio di utilizzo
queries = [
  "Integrazione con le API REST",
  "Protocolli di autenticazione",
  "Come distribuire in produzione", 
  "Tecniche di ottimizzazione delle prestazioni",
  "Migliori pratiche per la gestione degli errori"
]

results = batch_search_vector_store(
  "vs_abc123", 
  queries, 
  num_results: 3, 
  batch_size: 5
)

puts results
```

{% endtab %}
{% endtabs %}

### Ottimizzazione delle Prestazioni per Operazioni in Batch

Quando si implementano operazioni in batch per le ricerche nel vector store, considera queste migliori pratiche:

1. **Dimensionamento Ottimale del Batch**: Per la maggior parte delle applicazioni, elaborare 5-10 query in parallelo offre un buon equilibrio tra throughput e utilizzo delle risorse.
2. **Consapevolezza del Rate Limiting**: Includi meccanismi di ritardo tra i batch (tipicamente 1-2 secondi) per evitare di superare i limiti di velocità dell'API.
3. **Gestione degli Errori**: Implementa una gestione robusta degli errori per le singole query che potrebbero fallire all'interno di un batch.
4. **Gestione delle Connessioni**: Per applicazioni ad alto volume, implementa il pooling delle connessioni per ridurre il sovraccarico.
5. **Configurazione dei Timeout**: Imposta timeout appropriati per ogni richiesta per evitare che query a lungo termine blocchino l'intero batch.
6. **Elaborazione dei Risultati**: Considera di elaborare i risultati in modo asincrono man mano che diventano disponibili piuttosto che attendere tutti i risultati.
7. **Monitoraggio**: Monitora metriche di prestazione come il tempo medio di risposta e i tassi di successo per identificare opportunità di ottimizzazione.

Per applicazioni di produzione con volumi di query molto elevati, considera di implementare un sistema di coda con processi di lavoro per gestire grandi batch in modo efficiente.

Questo endpoint ti consente di cercare nel tuo vector store utilizzando la similarità semantica. Restituisce documenti che sono concettualmente correlati alla tua query, anche se non contengono le parole chiave esatte. Questo lo rende particolarmente potente per query in linguaggio naturale e risposte a domande.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rememberizer.ai/it/risorse-per-sviluppatori/api-docs/vector-store/search-for-vector-store-documents-by-semantic-similarity.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.