# Cerca documenti per somiglianza semantica

{% openapi src="/files/TgprWtaxn0x1jf4BJIMN" path="/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/documents/search/?q=Come%20integrare%20Rememberizer%20con%20applicazioni%20personalizzate&n=5&from=2023-01-01T00:00:00Z&to=2023-12-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

{% hint style="info" %}
Sostituisci `YOUR_JWT_TOKEN` con il tuo token JWT effettivo.
{% endhint %}
{% endtab %}

{% tab title="JavaScript" %}

```javascript
const searchDocuments = async (query, numResults = 5, from = null, to = null) => {
  const url = new URL('https://api.rememberizer.ai/api/v1/documents/search/');
  url.searchParams.append('q', query);
  url.searchParams.append('n', numResults);
  
  if (from) {
    url.searchParams.append('from', from);
  }
  
  if (to) {
    url.searchParams.append('to', to);
  }
  
  const response = await fetch(url.toString(), {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    }
  });
  
  const data = await response.json();
  console.log(data);
};

searchDocuments('Come integrare Rememberizer con applicazioni personalizzate', 5);
```

{% hint style="info" %}
Sostituisci `YOUR_JWT_TOKEN` con il tuo token JWT effettivo.
{% endhint %}
{% endtab %}

{% tab title="Python" %}

```python
import requests

def search_documents(query, num_results=5, from_date=None, to_date=None):
    headers = {
        "Authorization": "Bearer YOUR_JWT_TOKEN"
    }
    
    params = {
        "q": query,
        "n": num_results
    }
    
    if from_date:
        params["from"] = from_date
    
    if to_date:
        params["to"] = to_date
    
    response = requests.get(
        "https://api.rememberizer.ai/api/v1/documents/search/",
        headers=headers,
        params=params
    )
    
    data = response.json()
    print(data)

search_documents("Come integrare Rememberizer con applicazioni personalizzate", 5)
```

{% hint style="info" %}
Sostituisci `YOUR_JWT_TOKEN` con il tuo token JWT effettivo.
{% endhint %}
{% endtab %}

{% tab title="Ruby" %}

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

def search_documents(query, num_results=5, from_date=nil, to_date=nil)
  uri = URI('https://api.rememberizer.ai/api/v1/documents/search/')
  params = {
    q: query,
    n: num_results
  }
  
  params[:from] = from_date if from_date
  params[:to] = to_date if to_date
  
  uri.query = URI.encode_www_form(params)
  
  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = 'Bearer YOUR_JWT_TOKEN'
  
  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_documents("Come integrare Rememberizer con applicazioni personalizzate", 5)
```

{% hint style="info" %}
Sostituisci `YOUR_JWT_TOKEN` con il tuo token JWT effettivo.
{% endhint %}
{% endtab %}
{% endtabs %}

## Parametri di Query

| Parametro    | Tipo    | Descrizione                                                                                                     |
| ------------ | ------- | --------------------------------------------------------------------------------------------------------------- |
| q            | string  | **Obbligatorio.** Il testo della query di ricerca (fino a 400 parole).                                          |
| n            | integer | Numero di risultati da restituire. Predefinito: 3. Usa valori più alti (ad es., 10) per risultati più completi. |
| from         | string  | Inizio dell'intervallo di tempo per i documenti da cercare, in formato ISO 8601.                                |
| to           | string  | Fine dell'intervallo di tempo per i documenti da cercare, in formato ISO 8601.                                  |
| prev\_chunks | integer | Numero di chunk precedenti da includere per il contesto. Predefinito: 2.                                        |
| next\_chunks | integer | Numero di chunk successivi da includere per il contesto. Predefinito: 2.                                        |

## Formato di Risposta

```json
{
  "data_sources": [
    {
      "name": "Google Drive",
      "documents": 3
    },
    {
      "name": "Slack",
      "documents": 2
    }
  ],
  "matched_chunks": [
    {
      "document": {
        "id": 12345,
        "document_id": "1aBcD2efGhIjK3lMnOpQrStUvWxYz",
        "name": "Documentazione API di Rememberizer.pdf",
        "type": "application/pdf",
        "path": "/Documents/Rememberizer/Documentazione API.pdf",
        "url": "https://drive.google.com/file/d/1aBcD2efGhIjK3lMnOpQrStUvWxYz/view",
        "size": 250000,
        "created_time": "2023-05-10T14:30:00Z",
        "modified_time": "2023-06-15T09:45:00Z",
        "indexed_on": "2023-06-15T10:30:00Z",
        "integration": {
          "id": 101,
          "integration_type": "google_drive"
        }
      },
      "matched_content": "Per integrare Rememberizer con applicazioni personalizzate, puoi utilizzare il flusso di autenticazione OAuth2 per autorizzare la tua applicazione ad accedere ai dati di Rememberizer di un utente. Una volta autorizzata, la tua applicazione può utilizzare le API di Rememberizer per cercare documenti, recuperare contenuti e altro ancora.",
      "distance": 0.123
    },
    // ... più chunk corrispondenti
  ],
  "message": "Ricerca completata con successo",
  "code": "success"
}
```

## Suggerimenti per l'Ottimizzazione della Ricerca

### Per Rispondere a Domande

Quando cerchi una risposta a una domanda, prova a formulare la tua query come se fosse una risposta ideale. Ad esempio:

Invece di: "Che cos'è l'embedding vettoriale?" Prova: "L'embedding vettoriale è una tecnica che converte il testo in vettori numerici in uno spazio ad alta dimensione."

{% hint style="info" %}
Per una comprensione più profonda di come funzionano gli embedding vettoriali e perché questo approccio di ricerca è efficace, vedi [Cosa sono gli Embedding Vettoriali e i Database Vettoriali?](/it/background/what-are-vector-embeddings-and-vector-databases.md)
{% endhint %}

### Regolazione del Conteggio dei Risultati

* Inizia con `n=3` per risultati rapidi e ad alta rilevanza
* Aumenta a `n=10` o superiore per informazioni più complete
* Se la ricerca restituisce informazioni insufficienti, prova ad aumentare il parametro `n`

### Filtraggio Basato sul Tempo

Utilizza i parametri `from` e `to` per concentrarti su documenti di periodi di tempo specifici:

* Documenti recenti: Imposta `from` su una data recente
* Analisi storica: Specifica un intervallo di date specifico
* Escludere informazioni obsolete: Imposta una data `to` appropriata

## Operazioni in Batch

Per gestire in modo efficiente grandi volumi di query di ricerca, Rememberizer supporta operazioni in batch per ottimizzare le prestazioni e ridurre il sovraccarico delle chiamate API.

### Ricerca in Batch

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

```python
import requests
import time
import json
from concurrent.futures import ThreadPoolExecutor

def batch_search_documents(queries, num_results=5, batch_size=10):
    """
    Esegui ricerche in batch con più query
    
    Args:
        queries: Elenco di stringhe di query di ricerca
        num_results: Numero di risultati da restituire per query
        batch_size: Numero di query da elaborare in parallelo
    
    Returns:
        Elenco dei risultati di ricerca per ogni query
    """
    headers = {
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json"
    }
    
    results = []
    
    # Elabora le query in batch
    for i in range(0, len(queries), batch_size):
        batch = queries[i:i+batch_size]
        
        # Crea un pool di thread per inviare richieste in parallelo
        with ThreadPoolExecutor(max_workers=batch_size) as executor:
            futures = []
            
            for query in batch:
                params = {
                    "q": query,
                    "n": num_results
                }
                
                future = executor.submit(
                    requests.get,
                    "https://api.rememberizer.ai/api/v1/documents/search/",
                    headers=headers,
                    params=params
                )
                futures.append(future)
            
            # Raccogli i risultati man mano che vengono completati
            for future in futures:
                response = future.result()
                results.append(response.json())
        
        # Limitazione della velocità - pausa tra i batch per evitare il throttling dell'API
        if i + batch_size < len(queries):
            time.sleep(1)
    
    return results

# Esempio di utilizzo
queries = [
    "Come utilizzare OAuth con Rememberizer",
    "Opzioni di configurazione del database vettoriale",
    "Migliori pratiche per la ricerca semantica",
    # Aggiungi altre query se necessario
]

results = batch_search_documents(queries, num_results=3, batch_size=5)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
/**
 * Esegui ricerche in batch con più query
 * 
 * @param {string[]} queries - Elenco delle stringhe di query di ricerca
 * @param {number} numResults - Numero di risultati da restituire per query
 * @param {number} batchSize - Numero di query da elaborare in parallelo
 * @param {number} delayBetweenBatches - Millisecondi da attendere tra i batch
 * @returns {Promise<Array>} - Elenco dei risultati di ricerca per ogni query
 */
async function batchSearchDocuments(queries, numResults = 5, batchSize = 10, delayBetweenBatches = 1000) {
  const results = [];
  
  // Elabora le query in batch
  for (let i = 0; i < queries.length; i += batchSize) {
    const batch = queries.slice(i, i + batchSize);
    
    // Crea un array di promesse per richieste concorrenti
    const batchPromises = batch.map(query => {
      const url = new URL('https://api.rememberizer.ai/api/v1/documents/search/');
      url.searchParams.append('q', query);
      url.searchParams.append('n', numResults);
      
      return fetch(url.toString(), {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_JWT_TOKEN'
        }
      }).then(response => response.json());
    });
    
    // Attendi che tutte le richieste nel batch siano completate
    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
    
    // Limitazione della velocità - pausa tra i batch per evitare il throttling dell'API
    if (i + batchSize < queries.length) {
      await new Promise(resolve => setTimeout(resolve, delayBetweenBatches));
    }
  }
  
  return results;
}

// Esempio di utilizzo
const queries = [
  "Come utilizzare OAuth con Rememberizer",
  "Opzioni di configurazione del database vettoriale",
  "Migliori pratiche per la ricerca semantica",
  // Aggiungi altre query se necessario
];

batchSearchDocuments(queries, 3, 5)
  .then(results => console.log(results))
  .catch(error => console.error('Errore nella ricerca in batch:', error));
```

{% endtab %}

{% tab title="Ruby" %}

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

# Esegui ricerche in batch con più query
#
# @param queries [Array<String>] Elenco delle stringhe di query di ricerca
# @param num_results [Integer] Numero di risultati da restituire per query
# @param batch_size [Integer] Numero di query da elaborare in parallelo
# @param delay_between_batches [Float] Secondi da attendere tra i batch
# @return [Array] Elenco dei risultati di ricerca per ogni query
def batch_search_documents(queries, num_results = 5, batch_size = 10, delay_between_batches = 1.0)
  results = []
  
  # Elabora le query in batch
  queries.each_slice(batch_size).with_index do |batch, batch_index|
    # Crea un pool di thread per richieste concorrenti
    pool = Concurrent::FixedThreadPool.new(batch_size)
    futures = []
    
    batch.each do |query|
      futures << Concurrent::Future.execute(executor: pool) do
        uri = URI('https://api.rememberizer.ai/api/v1/documents/search/')
        params = {
          q: query,
          n: num_results
        }
        
        uri.query = URI.encode_www_form(params)
        
        request = Net::HTTP::Get.new(uri)
        request['Authorization'] = 'Bearer YOUR_JWT_TOKEN'
        
        http = Net::HTTP.new(uri.host, uri.port)
        http.use_ssl = true
        
        response = http.request(request)
        JSON.parse(response.body)
      end
    end
    
    # Raccogli i risultati da tutti i thread
    batch_results = futures.map(&:value)
    results.concat(batch_results)
    
    # Limitazione della velocità - pausa tra i batch per evitare il throttling dell'API
    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 = [
  "Come utilizzare OAuth con Rememberizer",
  "Opzioni di configurazione del database vettoriale",
  "Migliori pratiche per la ricerca semantica",
  # Aggiungi ulteriori query se necessario
]

results = batch_search_documents(queries, 3, 5)
puts results
```

{% endtab %}
{% endtabs %}

### Considerazioni sulle Prestazioni

Quando si implementano operazioni in batch, considera queste migliori pratiche:

1. **Dimensione Ottimale del Batch**: Inizia con dimensioni del batch di 5-10 query e adatta in base alle caratteristiche di prestazione della tua applicazione.
2. **Limitazione della Frequenza**: Includi ritardi tra i batch per prevenire il throttling dell'API. Un buon punto di partenza è di 1 secondo tra i batch.
3. **Gestione degli Errori**: Implementa una gestione degli errori robusta per gestire le richieste fallite all'interno dei batch.
4. **Gestione delle Risorse**: Monitora l'uso delle risorse lato client, in particolare con grandi dimensioni del batch, per prevenire un consumo eccessivo di memoria.
5. **Elaborazione delle Risposte**: Elabora i risultati del batch in modo asincrono quando possibile per migliorare l'esperienza dell'utente.

Per applicazioni ad alto volume, considera di implementare un sistema di coda per gestire in modo efficiente un gran numero di richieste di ricerca.

Questo endpoint fornisce potenti capacità di ricerca semantica in tutta la tua base di conoscenza. Utilizza embedding vettoriali per trovare contenuti basati sul significato piuttosto che su corrispondenze esatte di parole chiave.


---

# 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/search-for-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.