# Pesquisar documentos do Armazenamento Vetorial por similaridade semântica

{% openapi src="/files/7wfxJNjaZYJgvBWvXvoQ" path="/vector-stores/{vector-store-id}/documents/search" method="get" %}
[rememberizer\_openapi.yml](https://606058861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDrEOD8oYxrWDlC9WhJ3K%2Fuploads%2Fgit-blob-77b6137eeb641262ec8e531c78123c02b825b865%2Frememberizer_openapi.yml?alt=media\&token=85552d2b-b485-42dc-a027-aa2441b8ca9f)
{% endopenapi %}

## Exemplos de Solicitações

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

```bash
curl -X GET \
  "https://api.rememberizer.ai/api/v1/vector-stores/vs_abc123/documents/search?q=Como%20integrar%20nosso%20produto%20com%20sistemas%20de%20terceiros&n=5&prev_chunks=1&next_chunks=1" \
  -H "x-api-key: SUA_CHAVE_API"
```

{% hint style="info" %}
Substitua `SUA_CHAVE_API` pela sua chave de API do Vector Store real e `vs_abc123` pelo seu ID do 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': 'SUA_CHAVE_API'
    }
  });
  
  const data = await response.json();
  console.log(data);
};

searchVectorStore(
  'vs_abc123',
  'Como integrar nosso produto com sistemas de terceiros',
  5,
  1,
  1
);
```

{% hint style="info" %}
Substitua `SUA_CHAVE_API` pela sua chave de API do Vector Store real e `vs_abc123` pelo seu ID do 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": "SUA_CHAVE_API"
    }
    
    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',
    'Como integrar nosso produto com sistemas de terceiros',
    5,
    1,
    1
)
```

{% hint style="info" %}
Substitua `SUA_CHAVE_API` pela sua chave de API do Vector Store real e `vs_abc123` pelo seu ID do 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'] = 'SUA_CHAVE_API'
  
  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',
  'Como integrar nosso produto com sistemas de terceiros',
  5,
  1,
  1
)
```

{% hint style="info" %}
Substitua `SUA_CHAVE_API` pela sua chave de API do Vector Store real e `vs_abc123` pelo seu ID do Vector Store.
{% endhint %}
{% endtab %}
{% endtabs %}

## Parâmetros de Caminho

| Parâmetro       | Tipo   | Descrição                                                           |
| --------------- | ------ | ------------------------------------------------------------------- |
| vector-store-id | string | **Obrigatório.** O ID do armazenamento de vetores a ser pesquisado. |

## Parâmetros de Consulta

| Parâmetro    | Tipo    | Descrição                                                            |
| ------------ | ------- | -------------------------------------------------------------------- |
| q            | string  | **Obrigatório.** O texto da consulta de pesquisa.                    |
| n            | integer | Número de resultados a retornar. Padrão: 10.                         |
| t            | number  | Limite de correspondência. Padrão: 0.7.                              |
| prev\_chunks | integer | Número de partes antes da parte correspondente a incluir. Padrão: 0. |
| next\_chunks | integer | Número de partes após a parte correspondente a incluir. Padrão: 0.   |

## Formato de Resposta

```json
{
  "vector_store": {
    "id": "vs_abc123",
    "name": "Documentação do Produto"
  },
  "matched_chunks": [
    {
      "document": {
        "id": 1234,
        "name": "Guia de Integração.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": "Nosso produto oferece várias opções de integração para sistemas de terceiros. O método principal é através da nossa API RESTful, que suporta autenticação OAuth2. Além disso, você pode usar nosso SDK disponível em Python, JavaScript e Java.",
      "distance": 0.123
    },
    // ... mais partes correspondentes
  ]
}
```

## Autenticação

Este endpoint requer autenticação usando uma chave de API no cabeçalho `x-api-key`.

## Respostas de Erro

| Código de Status | Descrição                                                                   |
| ---------------- | --------------------------------------------------------------------------- |
| 400              | Solicitação Inválida - Parâmetros obrigatórios ausentes ou formato inválido |
| 401              | Não Autorizado - Chave de API inválida ou ausente                           |
| 404              | Não Encontrado - Armazenamento de Vetores não encontrado                    |
| 500              | Erro Interno do Servidor                                                    |

## Dicas de Otimização de Busca

### Janelas de Contexto

Use os parâmetros `prev_chunks` e `next_chunks` para controlar quanto contexto é incluído em cada correspondência:

* Defina ambos como 0 para correspondências precisas sem contexto
* Defina ambos como 1-2 para correspondências com contexto mínimo
* Defina ambos como 3-5 para correspondências com contexto substancial

### Limite de Correspondência

O parâmetro `t` controla quão rigorosamente as correspondências são filtradas:

* Valores mais altos (por exemplo, 0.9) retornam apenas correspondências muito próximas
* Valores mais baixos (por exemplo, 0.5) retornam mais correspondências com maior variedade
* O padrão (0.7) fornece uma abordagem equilibrada

## Operações em Lote

Para aplicações de alto desempenho, o Rememberizer suporta operações em lote eficientes em lojas de vetores. Esses métodos otimizam o desempenho ao processar várias consultas de pesquisa.

### Implementação de Busca em Lote

{% 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):
    """
    Realiza buscas em lote contra um armazenamento de vetores
    
    Args:
        vector_store_id: ID do armazenamento de vetores a ser pesquisado
        queries: Lista de strings de consulta de pesquisa
        num_results: Número de resultados por consulta
        batch_size: Número de requisições paralelas
        
    Returns:
        Lista de resultados da pesquisa
    """
    headers = {
        "x-api-key": "YOUR_API_KEY"
    }
    
    results = []
    
    # Processar em lotes para evitar sobrecarregar a 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
                }
                
                # Enviar a requisição para o pool de threads
                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)
            
            # Coletar resultados de todas as futures
            for future in futures:
                response = future.result()
                if response.status_code == 200:
                    results.append(response.json())
                else:
                    results.append({"error": f"Falhou com código de status: {response.status_code}"})
        
        # Adicionar um atraso entre os lotes para evitar limitação de taxa
        if i + batch_size < len(queries):
            time.sleep(1)
    
    return results

# Exemplo de uso
queries = [
    "Integração com APIs REST",
    "Protocolos de autenticação",
    "Como implantar em produção",
    "Técnicas de otimização de desempenho",
    "Melhores práticas de tratamento de erros"
]

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
/**
 * Realiza buscas em lote contra um armazenamento de vetores
 * 
 * @param {string} vectorStoreId - ID do armazenamento de vetores
 * @param {string[]} queries - Lista de consultas de busca
 * @param {Object} options - Opções de configuração
 * @returns {Promise<Array>} - Lista de resultados da busca
 */
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';
  
  // Processar em lotes para gerenciar a carga da API
  for (let i = 0; i < queries.length; i += batchSize) {
    const batchQueries = queries.slice(i, i + batchSize);
    
    // Criar array de promessas para requisições paralelas
    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: `Falhou com status: ${response.status}` };
        }
      })
      .catch(error => {
        return { error: error.message };
      });
    });
    
    // Aguardar todas as requisições do lote serem concluídas
    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
    
    // Adicionar atraso entre os lotes para evitar limitação de taxa
    if (i + batchSize < queries.length) {
      await new Promise(resolve => setTimeout(resolve, delayBetweenBatches));
    }
  }
  
  return results;
}

// Exemplo de uso
const queries = [
  "Integração com APIs REST",
  "Protocolos de autenticação",
  "Como implantar em produção",
  "Técnicas de otimização de desempenho",
  "Melhores práticas de tratamento de erros"
];

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("A busca em lote falhou:", error));
```

{% endtab %}

{% tab title="Ruby" %}

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

# Realizar buscas em lote contra um armazenamento de vetores
#
# @param vector_store_id [String] ID do armazenamento de vetores
# @param queries [Array<String>] Lista de consultas de pesquisa
# @param num_results [Integer] Número de resultados por consulta
# @param batch_size [Integer] Número de requisições paralelas
# @param delay_between_batches [Float] Segundos a esperar entre os lotes
# @return [Array] Resultados da pesquisa para cada consulta
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'
  
  # Processar em lotes
  queries.each_slice(batch_size).with_index do |batch_queries, batch_index|
    # Criar um pool de threads para execução concorrente
    pool = Concurrent::FixedThreadPool.new(batch_size)
    futures = []
    
    batch_queries.each do |query|
      # Enviar cada solicitação para o pool de threads
      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" => "Falha com o código de status: #{response.code}" }
          end
        rescue => e
          { "error" => e.message }
        end
      end
    end
    
    # Coletar resultados de todas as futures
    batch_results = futures.map(&:value)
    results.concat(batch_results)
    
    # Adicionar atraso entre os lotes
    if batch_index < (queries.length / batch_size.to_f).ceil - 1
      sleep(delay_between_batches)
    end
  end
  
  pool.shutdown
  results
end

# Exemplo de uso
queries = [
  "Integração com APIs REST",
  "Protocolos de autenticação",
  "Como implantar em produção", 
  "Técnicas de otimização de desempenho",
  "Melhores práticas de tratamento de erros"
]

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

puts results
```

{% endtab %}
{% endtabs %}

### Otimização de Desempenho para Operações em Lote

Ao implementar operações em lote para buscas em lojas de vetores, considere estas melhores práticas:

1. **Tamanho Ótimo do Lote**: Para a maioria das aplicações, processar de 5 a 10 consultas em paralelo oferece um bom equilíbrio entre throughput e uso de recursos.
2. **Consciência de Limitação de Taxa**: Inclua mecanismos de atraso entre os lotes (tipicamente 1-2 segundos) para evitar atingir os limites de taxa da API.
3. **Tratamento de Erros**: Implemente um tratamento de erros robusto para consultas individuais que podem falhar dentro de um lote.
4. **Gerenciamento de Conexões**: Para aplicações de alto volume, implemente pooling de conexões para reduzir a sobrecarga.
5. **Configuração de Timeout**: Defina timeouts apropriados para cada solicitação para evitar que consultas de longa duração bloqueiem todo o lote.
6. **Processamento de Resultados**: Considere processar resultados de forma assíncrona à medida que se tornam disponíveis, em vez de esperar por todos os resultados.
7. **Monitoramento**: Acompanhe métricas de desempenho, como tempo médio de resposta e taxas de sucesso, para identificar oportunidades de otimização.

Para aplicações de produção com volumes de consulta muito altos, considere implementar um sistema de fila com processos de trabalho para gerenciar grandes lotes de forma eficiente.

Este endpoint permite que você pesquise sua loja de vetores usando similaridade semântica. Ele retorna documentos que estão conceitualmente relacionados à sua consulta, mesmo que não contenham as palavras-chave exatas. Isso o torna particularmente poderoso para consultas em linguagem natural e respostas a perguntas.


---

# 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/pt/recursos-para-desenvolvedores/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.