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

{% openapi src="/files/WF90zszaISusKGEBimez" 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. **監控**：跟踪性能指標，如平均響應時間和成功率，以識別優化機會。

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

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


---

# 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/zh-hk/kai-fa-zhe-zi-yuan/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.