# 按語義相似性搜索向量儲存文件

{% openapi src="<https://2492455604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTVKmtXKPeA8gAZJsuGLA%2Fuploads%2Fgit-blob-77b6137eeb641262ec8e531c78123c02b825b865%2Frememberizer_openapi.yml?alt=media&token=3b4a9db2-4dd7-440f-b670-9555703d351d>" path="/vector-stores/{vector-store-id}/documents/search" method="get" %}
[rememberizer\_openapi.yml](https://2492455604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTVKmtXKPeA8gAZJsuGLA%2Fuploads%2Fgit-blob-77b6137eeb641262ec8e531c78123c02b825b865%2Frememberizer_openapi.yml?alt=media\&token=3b4a9db2-4dd7-440f-b670-9555703d351d)
{% endopenapi %}

## 示例請求

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

```bash
curl -X GET \
  "https://api.rememberizer.ai/api/v1/vector-stores/vs_abc123/documents/search?q=如何%20將%20我們的%20產品%20與%20第三方%20系統%20整合&n=5&prev_chunks=1&next_chunks=1" \
  -H "x-api-key: YOUR_API_KEY"
```

{% hint style="info" %}
將 `YOUR_API_KEY` 替換為您的實際向量存儲 API 金鑰，並將 `vs_abc123` 替換為您的向量存儲 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',
  '如何將我們的產品與第三方系統整合',
  5,
  1,
  1
);
```

{% hint style="info" %}
將 `YOUR_API_KEY` 替換為您的實際向量存儲 API 金鑰，並將 `vs_abc123` 替換為您的向量存儲 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',
    '如何將我們的產品與第三方系統整合',
    5,
    1,
    1
)
```

{% hint style="info" %}
將 `YOUR_API_KEY` 替換為您的實際向量存儲 API 金鑰，並將 `vs_abc123` 替換為您的向量存儲 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',
  '如何將我們的產品與第三方系統整合',
  5,
  1,
  1
)
```

{% hint style="info" %}
將 `YOUR_API_KEY` 替換為您的實際向量存儲 API 金鑰，並將 `vs_abc123` 替換為您的向量存儲 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": "我們的產品提供多種第三方系統的整合選項。主要方法是通過我們的 RESTful API，該 API 支持 OAuth2 認證。此外，您還可以使用我們提供的 SDK，支持 Python、JavaScript 和 Java。",
      "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):
    """
    對向量儲存庫執行批次搜尋
    
    參數:
        vector_store_id: 要搜尋的向量儲存庫的 ID
        queries: 搜尋查詢字串的列表
        num_results: 每個查詢的結果數量
        batch_size: 平行請求的數量
        
    回傳:
        搜尋結果的列表
    """
    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)
            
            # 收集所有未來的結果
            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. **速率限制意識**：在批次之間包含延遲機制（通常為 1-2 秒），以避免觸及 API 速率限制。
3. **錯誤處理**：為可能在批次中失敗的單個查詢實施健壯的錯誤處理。
4. **連接管理**：對於高流量應用程序，實施連接池以減少開銷。
5. **超時配置**：為每個請求設置適當的超時，以防止長時間運行的查詢阻塞整個批次。
6. **結果處理**：考慮在結果可用時異步處理結果，而不是等待所有結果。
7. **監控**：跟踪性能指標，如平均響應時間和成功率，以識別優化機會。

對於查詢量非常大的生產應用程序，考慮實施隊列系統和工作進程以有效管理大型批次。

此端點允許您使用語義相似性搜索您的向量存儲。它返回與您的查詢在概念上相關的文檔，即使它們不包含確切的關鍵字。這使得它對自然語言查詢和問題回答特別強大。