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

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

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
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-07-04T03:57:00.968Z",
        "vector_store": "text",
        "created": "2025-07-04T03:57:00.968Z",
        "modified": "2025-07-04T03:57:00.968Z"
      },
      "matched_content": "text",
      "distance": 1
    }
  ]
}

예제 요청

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로 교체하세요.

경로 매개변수

매개변수
유형
설명

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_chunksnext_chunks 매개변수를 사용하여 각 일치 항목에 포함되는 컨텍스트의 양을 제어합니다:

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

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

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

일치 임계값

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

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

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

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

배치 작업

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

배치 검색 구현

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)

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

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

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

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

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

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

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

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

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

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

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

Last updated