Buscar documentos del Almacenamiento de Vectores por similitud semántica

Buscar documentos de Vector Store con similitud semántica y operaciones por lotes

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-01T01:29:48.749Z",
        "vector_store": "text",
        "created": "2025-05-01T01:29:48.749Z",
        "modified": "2025-05-01T01:29:48.749Z"
      },
      "matched_content": "text",
      "distance": 1
    }
  ]
}

Ejemplos de Solicitudes

cURL

curl -X GET \
  "https://api.rememberizer.ai/api/v1/vector-stores/vs_abc123/documents/search?q=Cómo%20integrar%20nuestro%20producto%20con%20sistemas%20de%20terceros&n=5&prev_chunks=1&next_chunks=1" \
  -H "x-api-key: YOUR_API_KEY"

Reemplace YOUR_API_KEY con su clave API real de Vector Store y vs_abc123 con su ID de 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': 'YOUR_API_KEY'
    }
  });
  
  const data = await response.json();
  console.log(data);
};

searchVectorStore(
  'vs_abc123',
  'Cómo integrar nuestro producto con sistemas de terceros',
  5,
  1,
  1
);

Reemplace YOUR_API_KEY con su clave API real de Vector Store y vs_abc123 con su ID de 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": "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',
    'Cómo integrar nuestro producto con sistemas de terceros',
    5,
    1,
    1
)

Reemplace YOUR_API_KEY con su clave API real de Vector Store y vs_abc123 con su ID de 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'] = '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',
  'Cómo integrar nuestro producto con sistemas de terceros',
  5,
  1,
  1
)

Reemplace YOUR_API_KEY con su clave API real de Vector Store y vs_abc123 con su ID de Vector Store.

Parámetros de Ruta

Parámetro	Tipo	Descripción
vector-store-id	string	Requerido. El ID de la tienda de vectores en la que buscar.

Parámetros de Consulta

Parámetro	Tipo	Descripción
q	cadena	Requerido. El texto de la consulta de búsqueda.
n	entero	Número de resultados a devolver. Predeterminado: 10.
t	número	Umbral de coincidencia. Predeterminado: 0.7.
prev_chunks	entero	Número de fragmentos antes del fragmento coincidente a incluir. Predeterminado: 0.
next_chunks	entero	Número de fragmentos después del fragmento coincidente a incluir. Predeterminado: 0.

Formato de Respuesta

{
  "vector_store": {
    "id": "vs_abc123",
    "name": "Documentación del Producto"
  },
  "matched_chunks": [
    {
      "document": {
        "id": 1234,
        "name": "Guía de Integración.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": "Nuestro producto ofrece varias opciones de integración para sistemas de terceros. El método principal es a través de nuestra API RESTful, que admite autenticación OAuth2. Además, puedes usar nuestro SDK disponible en Python, JavaScript y Java.",
      "distance": 0.123
    },
    // ... más fragmentos coincidentes
  ]
}

Autenticación

Este endpoint requiere autenticación utilizando una clave API en el encabezado x-api-key.

Respuestas de Error

Código de Estado	Descripción
400	Solicitud Incorrecta - Faltan parámetros requeridos o formato inválido
401	No Autorizado - Clave API inválida o faltante
404	No Encontrado - Almacén de Vectores no encontrado
500	Error Interno del Servidor

Consejos de Optimización de Búsqueda

Ventanas de Contexto

Utiliza los parámetros prev_chunks y next_chunks para controlar cuánto contexto se incluye con cada coincidencia:

• Establece ambos en 0 para coincidencias precisas sin contexto

• Establece ambos en 1-2 para coincidencias con contexto mínimo

• Establece ambos en 3-5 para coincidencias con contexto sustancial

Umbral de Coincidencia

El parámetro t controla cuán estrictamente se filtran las coincidencias:

• Valores más altos (por ejemplo, 0.9) devuelven solo coincidencias muy cercanas

• Valores más bajos (por ejemplo, 0.5) devuelven más coincidencias con mayor variedad

• El valor predeterminado (0.7) proporciona un enfoque equilibrado

Operaciones por Lotes

Para aplicaciones de alto rendimiento, Rememberizer admite operaciones por lotes eficientes en almacenes de vectores. Estos métodos optimizan el rendimiento al procesar múltiples consultas de búsqueda.

Implementación de Búsqueda por Lotes

Python

import requests
import time
import concurrent.futures

def batch_search_vector_store(vector_store_id, queries, num_results=5, batch_size=10):
    """
    Realiza búsquedas por lotes en un almacén de vectores
    
    Args:
        vector_store_id: ID del almacén de vectores a buscar
        queries: Lista de cadenas de consulta de búsqueda
        num_results: Número de resultados por consulta
        batch_size: Número de solicitudes paralelas
        
    Returns:
        Lista de resultados de búsqueda
    """
    headers = {
        "x-api-key": "YOUR_API_KEY"
    }
    
    results = []
    
    # Procesar en lotes para evitar abrumar la 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 la solicitud al grupo de hilos
                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)
            
            # Recoger resultados de todos los futuros
            for future in futures:
                response = future.result()
                if response.status_code == 200:
                    results.append(response.json())
                else:
                    results.append({"error": f"Falló con el código de estado: {response.status_code}"})
        
        # Agregar un retraso entre lotes para evitar limitaciones de tasa
        if i + batch_size < len(queries):
            time.sleep(1)
    
    return results

# Ejemplo de uso
queries = [
    "Integración con APIs REST",
    "Protocolos de autenticación",
    "Cómo desplegar en producción",
    "Técnicas de optimización de rendimiento",
    "Mejores prácticas para el manejo de errores"
]

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

JavaScript

/**
 * Realizar búsquedas por lotes en un almacén de vectores
 * 
 * @param {string} vectorStoreId - ID del almacén de vectores
 * @param {string[]} queries - Lista de consultas de búsqueda
 * @param {Object} options - Opciones de configuración
 * @returns {Promise<Array>} - Lista de resultados de búsqueda
 */
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';
  
  // Procesar en lotes para gestionar la carga de la API
  for (let i = 0; i < queries.length; i += batchSize) {
    const batchQueries = queries.slice(i, i + batchSize);
    
    // Crear un array de promesas para solicitudes 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: `Falló con estado: ${response.status}` };
        }
      })
      .catch(error => {
        return { error: error.message };
      });
    });
    
    // Esperar a que todas las solicitudes en el lote se completen
    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
    
    // Agregar un retraso entre lotes para evitar limitaciones de tasa
    if (i + batchSize < queries.length) {
      await new Promise(resolve => setTimeout(resolve, delayBetweenBatches));
    }
  }
  
  return results;
}

// Ejemplo de uso
const queries = [
  "Integración con APIs REST",
  "Protocolos de autenticación",
  "Cómo desplegar en producción",
  "Técnicas de optimización de rendimiento",
  "Mejores prácticas para el manejo de errores"
];

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 búsqueda por lotes falló:", error));

Ruby

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

# Realizar búsquedas por lotes en un almacén de vectores
#
# @param vector_store_id [String] ID de la tienda de vectores
# @param queries [Array<String>] Lista de consultas de búsqueda
# @param num_results [Integer] Número de resultados por consulta
# @param batch_size [Integer] Número de solicitudes paralelas
# @param delay_between_batches [Float] Segundos a esperar entre lotes
# @return [Array] Resultados de búsqueda 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'
  
  # Procesar en lotes
  queries.each_slice(batch_size).with_index do |batch_queries, batch_index|
    # Crear un grupo de hilos para ejecución concurrente
    pool = Concurrent::FixedThreadPool.new(batch_size)
    futures = []
    
    batch_queries.each do |query|
      # Enviar cada solicitud al grupo de hilos
      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" => "Falló con el código de estado: #{response.code}" }
          end
        rescue => e
          { "error" => e.message }
        end
      end
    end
    
    # Recoger resultados de todos los futuros
    batch_results = futures.map(&:value)
    results.concat(batch_results)
    
    # Agregar retraso entre lotes
    if batch_index < (queries.length / batch_size.to_f).ceil - 1
      sleep(delay_between_batches)
    end
  end
  
  pool.shutdown
  results
end

# Ejemplo de uso
queries = [
  "Integración con APIs REST",
  "Protocolos de autenticación",
  "Cómo desplegar en producción", 
  "Técnicas de optimización de rendimiento",
  "Mejores prácticas para el manejo de errores"
]

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

puts results

Optimización del Rendimiento para Operaciones por Lotes

Al implementar operaciones por lotes para búsquedas en el almacén de vectores, considera estas mejores prácticas:

1. Tamaño Óptimo del Lote: Para la mayoría de las aplicaciones, procesar de 5 a 10 consultas en paralelo proporciona un buen equilibrio entre rendimiento y uso de recursos.

2. Conciencia del Límite de Tasa: Incluye mecanismos de retraso entre lotes (típicamente de 1 a 2 segundos) para evitar alcanzar los límites de tasa de la API.

3. Manejo de Errores: Implementa un manejo de errores robusto para consultas individuales que puedan fallar dentro de un lote.

4. Gestión de Conexiones: Para aplicaciones de alto volumen, implementa agrupamiento de conexiones para reducir la sobrecarga.

5. Configuración de Tiempo de Espera: Establece tiempos de espera apropiados para cada solicitud para evitar que consultas de larga duración bloqueen todo el lote.

6. Procesamiento de Resultados: Considera procesar los resultados de manera asíncrona a medida que estén disponibles en lugar de esperar a que todos los resultados lleguen.

7. Monitoreo: Realiza un seguimiento de métricas de rendimiento como el tiempo de respuesta promedio y las tasas de éxito para identificar oportunidades de optimización.

Para aplicaciones de producción con volúmenes de consultas muy altos, considera implementar un sistema de cola con procesos de trabajo para gestionar grandes lotes de manera eficiente.

Este punto final te permite buscar en tu almacén de vectores utilizando similitud semántica. Devuelve documentos que están conceptualmente relacionados con tu consulta, incluso si no contienen las palabras clave exactas. Esto lo hace particularmente poderoso para consultas en lenguaje natural y respuestas a preguntas.