의미적 유사성으로 벡터 저장소 문서 검색하기

의미적 유사성과 배치 작업으로 벡터 저장소 문서 검색

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-24T11:40:58.983Z",
        "vector_store": "text",
        "created": "2025-05-24T11:40:58.983Z",
        "modified": "2025-05-24T11:40:58.983Z"
      },
      "matched_content": "text",
      "distance": 1
    }
  ]
}

예제 요청

cURL

curl -X GET \
  "https://api.rememberizer.ai/api/v1/vector-stores/vs_abc123/documents/search?q=How%20to%20integrate%20our%20product%20with%20third-party%20systems&n=5&prev_chunks=1&next_chunks=1" \
  -H "x-api-key: YOUR_API_KEY"

YOUR_API_KEY를 실제 Vector Store API 키로 교체하고 vs_abc123를 Vector Store ID로 교체하세요.

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',
  'How to integrate our product with third-party systems',
  5,
  1,
  1
);

YOUR_API_KEY를 실제 Vector Store API 키로 교체하고 vs_abc123를 Vector Store ID로 교체하세요.

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',
    'How to integrate our product with third-party systems',
    5,
    1,
    1
)

YOUR_API_KEY를 실제 Vector Store API 키로 교체하고 vs_abc123를 Vector Store ID로 교체하세요.

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',
  'How to integrate our product with third-party systems',
  5,
  1,
  1
)

YOUR_API_KEY를 실제 Vector Store API 키로 교체하고 vs_abc123를 Vector Store ID로 교체하세요.

경로 매개변수

매개변수	유형	설명
vector-store-id	문자열	필수. 검색할 벡터 저장소의 ID입니다.

쿼리 매개변수

매개변수	유형	설명
q	문자열	필수. 검색 쿼리 텍스트.
n	정수	반환할 결과 수. 기본값: 10.
t	숫자	일치 임계값. 기본값: 0.7.
prev_chunks	정수	일치하는 청크 이전에 포함할 청크 수. 기본값: 0.
next_chunks	정수	일치하는 청크 이후에 포함할 청크 수. 기본값: 0.

응답 형식

{
  "vector_store": {
    "id": "vs_abc123",
    "name": "제품 문서"
  },
  "matched_chunks": [
    {
      "document": {
        "id": 1234,
        "name": "통합 가이드.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": "우리 제품은 서드파티 시스템을 위한 여러 통합 옵션을 제공합니다. 주요 방법은 OAuth2 인증을 지원하는 RESTful API를 통한 것입니다. 또한 Python, JavaScript 및 Java에서 사용할 수 있는 SDK를 사용할 수 있습니다.",
      "distance": 0.123
    },
    // ... 더 많은 일치하는 청크
  ]
}

인증

이 엔드포인트는 x-api-key 헤더에 API 키를 사용하여 인증이 필요합니다.

오류 응답

상태 코드	설명
400	잘못된 요청 - 필수 매개변수가 누락되었거나 형식이 잘못됨
401	인증되지 않음 - 잘못되었거나 누락된 API 키
404	찾을 수 없음 - 벡터 저장소를 찾을 수 없음
500	내부 서버 오류

검색 최적화 팁

컨텍스트 윈도우

prev_chunks 및 next_chunks 매개변수를 사용하여 각 일치 항목에 포함되는 컨텍스트의 양을 제어합니다:

• 정확한 일치를 위해 둘 다 0으로 설정

• 최소한의 컨텍스트가 있는 일치를 위해 둘 다 1-2로 설정

• 상당한 컨텍스트가 있는 일치를 위해 둘 다 3-5로 설정

일치 임계값

t 매개변수는 일치 항목이 얼마나 엄격하게 필터링되는지를 제어합니다:

• 높은 값(예: 0.9)은 매우 가까운 일치 항목만 반환합니다

• 낮은 값(예: 0.5)은 더 다양한 일치 항목을 반환합니다

• 기본값(0.7)은 균형 잡힌 접근 방식을 제공합니다

배치 작업

고속 처리 애플리케이션을 위해 Rememberizer는 벡터 저장소에서 효율적인 배치 작업을 지원합니다. 이러한 방법은 여러 검색 쿼리를 처리할 때 성능을 최적화합니다.

배치 검색 구현

Python

import requests
import time
import concurrent.futures

def batch_search_vector_store(vector_store_id, queries, num_results=5, batch_size=10):
    """
    벡터 저장소에 대해 배치 검색 수행
    
    Args:
        vector_store_id: 검색할 벡터 저장소의 ID
        queries: 검색 쿼리 문자열 목록
        num_results: 쿼리당 결과 수
        batch_size: 병렬 요청 수
        
    Returns:
        검색 결과 목록
    """
    headers = {
        "x-api-key": "YOUR_API_KEY"
    }
    
    results = []
    
    # 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
                }
                
                # 스레드 풀에 요청 제출
                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)
            
            # 모든 future에서 결과 수집
            for future in futures:
                response = future.result()
                if response.status_code == 200:
                    results.append(response.json())
                else:
                    results.append({"error": f"상태 코드로 실패: {response.status_code}"})
        
        # 비율 제한을 피하기 위해 배치 간 지연 추가
        if i + batch_size < len(queries):
            time.sleep(1)
    
    return results

# 예제 사용법
queries = [
    "REST API와의 통합",
    "인증 프로토콜",
    "프로덕션에 배포하는 방법",
    "성능 최적화 기법",
    "오류 처리 모범 사례"
]

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

JavaScript

/**
 * 벡터 저장소에 대해 배치 검색 수행
 * 
 * @param {string} vectorStoreId - 벡터 저장소 ID
 * @param {string[]} queries - 검색 쿼리 목록
 * @param {Object} options - 구성 옵션
 * @returns {Promise<Array>} - 검색 결과 목록
 */
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';
  
  // API 부하 관리를 위해 배치로 처리
  for (let i = 0; i < queries.length; i += batchSize) {
    const batchQueries = queries.slice(i, i + batchSize);
    
    // 병렬 요청을 위한 프로미스 배열 생성
    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: `상태: ${response.status}로 실패했습니다.` };
        }
      })
      .catch(error => {
        return { error: error.message };
      });
    });
    
    // 배치 내 모든 요청이 완료될 때까지 대기
    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
    
    // 속도 제한을 피하기 위해 배치 간 지연 추가
    if (i + batchSize < queries.length) {
      await new Promise(resolve => setTimeout(resolve, delayBetweenBatches));
    }
  }
  
  return results;
}

// 예제 사용법
const queries = [
  "REST API와의 통합",
  "인증 프로토콜",
  "프로덕션에 배포하는 방법",
  "성능 최적화 기법",
  "오류 처리 모범 사례"
];

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("배치 검색 실패:", error));

Ruby

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

# 벡터 저장소에 대한 배치 검색 수행
#
# @param vector_store_id [String] 벡터 스토어의 ID
# @param queries [Array<String>] 검색 쿼리 목록
# @param num_results [Integer] 쿼리당 결과 수
# @param batch_size [Integer] 병렬 요청 수
# @param delay_between_batches [Float] 배치 간 대기할 초
# @return [Array] 각 쿼리에 대한 검색 결과
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'
  
  # 배치로 처리
  queries.each_slice(batch_size).with_index do |batch_queries, batch_index|
    # 동시 실행을 위한 스레드 풀 생성
    pool = Concurrent::FixedThreadPool.new(batch_size)
    futures = []
    
    batch_queries.each do |query|
      # 각 요청을 스레드 풀에 제출
      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" => "상태 코드로 실패: #{response.code}" }
          end
        rescue => e
          { "error" => e.message }
        end
      end
    end
    
    # 모든 futures에서 결과 수집
    batch_results = futures.map(&:value)
    results.concat(batch_results)
    
    # 배치 간 지연 추가
    if batch_index < (queries.length / batch_size.to_f).ceil - 1
      sleep(delay_between_batches)
    end
  end
  
  pool.shutdown
  results
end

# 예제 사용법
queries = [
  "REST API와의 통합",
  "인증 프로토콜",
  "프로덕션에 배포하는 방법", 
  "성능 최적화 기법",
  "오류 처리 모범 사례"
]

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

puts results

배치 작업을 위한 성능 최적화

벡터 저장소 검색을 위한 배치 작업을 구현할 때 다음의 모범 사례를 고려하세요:

1. 최적의 배치 크기: 대부분의 애플리케이션에서는 5-10개의 쿼리를 병렬로 처리하는 것이 처리량과 자원 사용 간의 좋은 균형을 제공합니다.

2. 속도 제한 인식: API 속도 제한에 걸리지 않도록 배치 간에 지연 메커니즘(일반적으로 1-2초)을 포함하세요.

3. 오류 처리: 배치 내에서 실패할 수 있는 개별 쿼리에 대해 강력한 오류 처리를 구현하세요.

4. 연결 관리: 대량의 애플리케이션의 경우 오버헤드를 줄이기 위해 연결 풀링을 구현하세요.

5. 타임아웃 구성: 전체 배치가 차단되지 않도록 각 요청에 적절한 타임아웃을 설정하세요.

6. 결과 처리: 모든 결과를 기다리기보다는 결과가 제공되는 대로 비동기적으로 처리하는 것을 고려하세요.

7. 모니터링: 평균 응답 시간 및 성공률과 같은 성능 지표를 추적하여 최적화 기회를 식별하세요.

쿼리 볼륨이 매우 높은 프로덕션 애플리케이션의 경우, 대규모 배치를 효율적으로 관리하기 위해 작업 프로세스가 있는 큐 시스템을 구현하는 것을 고려하세요.

이 엔드포인트는 의미적 유사성을 사용하여 벡터 저장소를 검색할 수 있게 해줍니다. 이는 쿼리와 개념적으로 관련된 문서를 반환하며, 정확한 키워드를 포함하지 않더라도 가능합니다. 이는 자연어 쿼리 및 질문 응답에 특히 강력합니다.