Pesquisar documentos do Armazenamento Vetorial por similaridade semântica

Pesquisar documentos do Armazenamento Vetorial com semelhança semântica e operações em lote

get

Initiate a search operation with a query text and receive most semantically similar responses from the vector store.

Path parameters

vector-store-idstringRequired

The ID of the vector store.

Query parameters

qstringRequired

The search query text.

nintegerOptional

Number of chunks to return.

tnumberOptional

Matching threshold.

prev_chunksintegerOptional

Number of chunks before the matched chunk to include.

next_chunksintegerOptional

Number of chunks after the matched chunk to include.

Header parameters

x-api-keystringRequired

The API key for authentication.

Responses

200

Search results retrieved successfully.

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/vector-stores/{vector-store-id}/documents/search HTTP/1.1
Host: api.rememberizer.ai
x-api-key: text
Accept: */*

200

Search results retrieved successfully.

{
  "vector_store": {
    "id": "text",
    "name": "text"
  },
  "matched_chunks": [
    {
      "document": {
        "id": 1,
        "name": "text",
        "type": "text",
        "size": 1,
        "indexed_on": "2025-05-23T18:06:00.951Z",
        "vector_store": "text",
        "created": "2025-05-23T18:06:00.951Z",
        "modified": "2025-05-23T18:06:00.951Z"
      },
      "matched_content": "text",
      "distance": 1
    }
  ]
}

Exemplos de Solicitações

cURL

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"

Substitua SUA_CHAVE_API pela sua chave de API do Vector Store real e vs_abc123 pelo seu ID do Vector Store.

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
);

Substitua SUA_CHAVE_API pela sua chave de API do Vector Store real e vs_abc123 pelo seu ID do Vector Store.

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
)

Substitua SUA_CHAVE_API pela sua chave de API do Vector Store real e vs_abc123 pelo seu ID do Vector Store.

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
)

Substitua SUA_CHAVE_API pela sua chave de API do Vector Store real e vs_abc123 pelo seu ID do Vector Store.

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

{
  "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

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)

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));

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

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.