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

{% openapi src="/files/fAmF2Kwil50sF5cXMoEX" path="/vector-stores/{vector-store-id}/documents/search" method="get" %}
[rememberizer\_openapi.yml](https://2913883985-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fs0e4JCKQXzEGPRlMO7nt%2Fuploads%2Fgit-blob-77b6137eeb641262ec8e531c78123c02b825b865%2Frememberizer_openapi.yml?alt=media\&token=ac0eeb18-73cf-42a3-93fe-2ff232a978a3)
{% endopenapi %}

## 예제 요청

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

```bash
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"
```

{% hint style="info" %}
`YOUR_API_KEY`를 실제 Vector Store API 키로 교체하고 `vs_abc123`를 Vector Store ID로 교체하세요.
{% 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': '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
);
```

{% hint style="info" %}
`YOUR_API_KEY`를 실제 Vector Store API 키로 교체하고 `vs_abc123`를 Vector Store ID로 교체하세요.
{% 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": "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
)
```

{% hint style="info" %}
`YOUR_API_KEY`를 실제 Vector Store API 키로 교체하고 `vs_abc123`를 Vector Store ID로 교체하세요.
{% 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'] = '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
)
```

{% hint style="info" %}
`YOUR_API_KEY`를 실제 Vector Store API 키로 교체하고 `vs_abc123`를 Vector Store ID로 교체하세요.
{% endhint %}
{% endtab %}
{% endtabs %}

## 경로 매개변수

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

## 쿼리 매개변수

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

## 응답 형식

```json
{
  "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는 벡터 저장소에서 효율적인 배치 작업을 지원합니다. 이러한 방법은 여러 검색 쿼리를 처리할 때 성능을 최적화합니다.

### 배치 검색 구현

{% 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):
    """
    벡터 저장소에 대해 배치 검색 수행
    
    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)
```

{% endtab %}

{% tab title="JavaScript" %}

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

{% endtab %}

{% tab title="Ruby" %}

```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
```

{% endtab %}
{% endtabs %}

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

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

1. **최적의 배치 크기**: 대부분의 애플리케이션에서는 5-10개의 쿼리를 병렬로 처리하는 것이 처리량과 자원 사용 간의 좋은 균형을 제공합니다.
2. **속도 제한 인식**: API 속도 제한에 걸리지 않도록 배치 간에 지연 메커니즘(일반적으로 1-2초)을 포함하세요.
3. **오류 처리**: 배치 내에서 실패할 수 있는 개별 쿼리에 대해 강력한 오류 처리를 구현하세요.
4. **연결 관리**: 대량의 애플리케이션의 경우 오버헤드를 줄이기 위해 연결 풀링을 구현하세요.
5. **타임아웃 구성**: 전체 배치가 차단되지 않도록 각 요청에 적절한 타임아웃을 설정하세요.
6. **결과 처리**: 모든 결과를 기다리기보다는 결과가 제공되는 대로 비동기적으로 처리하는 것을 고려하세요.
7. **모니터링**: 평균 응답 시간 및 성공률과 같은 성능 지표를 추적하여 최적화 기회를 식별하세요.

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

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


---

# 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/ko/undefined-1/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.