在搜尋索引中設定向量化工具

備註

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

在 Foundry IQ(Azure AI 搜尋服務)中,向量器會在查詢執行時將文字或影像轉換為向量,讓您無需自行計算嵌入,即可針對向量欄位提交純文字查詢。

向量化工具會在搜尋索引中定義,並透過向量設定檔指派給向量欄位。 在查詢時,向量器會呼叫一個嵌入模型,從你的查詢輸入產生向量。 欲了解更多資訊,請參閱 查詢中使用整合向量化。

要在索引中新增向量工具,請使用 Azure 入口網站的匯入嚮導或索引設計器、索引 - 建立或更新 (REST API),或使用 Azure SDK 套件。 本文使用 REST 進行說明。

小提示

向量器負責查詢時的向量化。 若要在索引過程中也將內容向量化,請設置索引器和嵌入技能組。 欲了解更多資訊,請參閱 索引期間使用整合向量化。

先決條件

支援的內嵌模型

Foundry IQ 提供多種類型的向量器,每種都搭配對應的技能集。 技能在索引時產生嵌入,而向量器則在查詢時產生嵌入。 您必須為兩者使用相同的嵌入模型,因此請選擇指向相同模型部署的向量化工具–技能組配對。

更改向量器並不會重新產生已索引的文件向量。 若要取代現有索引所使用的模型,請參閱 「遷移嵌入模型」。

下表列出向量器及其支援模型與相關技能。

向量化工具 支援的模型 相關聯的技能
Azure OpenAI text-embedding-ada-002
text-embedding-3-large
text-embedding-3-small
Azure OpenAI Embedding
Microsoft Foundry 模型目錄(預覽版) Cohere-embed-v3-english
Cohere-embed-v3-多語系版
Cohere-embed-v4 1
AML
Azure Vision(預覽) 多模態嵌入 4.0 API Azure Vision multimodal embeddings (preview)
自訂 Web API 任何嵌入模型(外部託管) 自訂網頁 API

1 您只能透過 AML 技能或 embed-v-4-0以程式設計方式指定,無法透過 Azure 入口網站進行。 不過,您可以在之後使用入口網站來管理技能集或向量化器。

備註

只要您使用正式發行的技能組–向量化工具配對,向量化工具即為正式發行。 如需最新的可用性資訊,請參閱前表中每個向量化器和技能的文件。

使用精靈定義向量生成器

Azure 入口網站的 匯入資料 精靈可以讀取 Azure Blob 儲存體 的檔案,建立包含分塊和向量化欄位的索引,並新增向量器。 依設計,精靈產生的向量化工具會設定為與用於為 Blob 內容建立索引的相同嵌入模型。

要使用向量器建立樣本索引,請使用精靈:

  1. 將檔案上傳到 Azure 儲存體 中的容器。 我們使用 了 NASA 電子書《夜之地球》中的小型文字檔 ,在免費的 Foundry IQ 服務上測試這些說明。

  2. 執行 匯入資料 精靈。 選擇資料來源的 blob 容器。

    連線至您的資料頁面的螢幕截圖。

  3. 選擇向量器類型,若適用,則選擇模型部署。 此範例使用 Azure OpenAI 及 text-embedding-ada-002 部署。

    用於配置向量器嵌入模型的向量化與豐富資料頁面截圖。

  4. 當精靈完成且所有索引處理完成後,你應該會有一個索引,並有一個可搜尋的向量欄位。 欄位的 JSON 定義如下所示:

     {
       "name": "text_vector",
       "type": "Collection(Edm.Single)",
       "searchable": true,
       "filterable": false,
       "retrievable": true,
       "stored": true,
       "sortable": false,
       "facetable": false,
       "key": false,
       "dimensions": 1536,
       "vectorSearchProfile": "vector-nasa-ebook-text-profile",
       "synonymMaps": []
     }
    

    你也應該有向量剖面、向量搜尋演算法和向量化器。 他們的 JSON 定義如下:

     "algorithms": [
       {
         "name": "vector-nasa-ebook-text-algorithm",
         "kind": "hnsw",
         "hnswParameters": {
           "metric": "cosine",
           "m": 4,
           "efConstruction": 400,
           "efSearch": 500
         }
       }
     ],
    "profiles": [
       {
         "name": "vector-nasa-ebook-text-profile",
         "algorithm": "vector-nasa-ebook-text-algorithm",
         "vectorizer": "vector-nasa-ebook-text-vectorizer"
       }
     ],
     "vectorizers": [
       {
         "name": "vector-nasa-ebook-text-vectorizer",
         "kind": "azureOpenAI",
         "azureOpenAIParameters": {
           "resourceUri": "https://my-azure-openai-resource.openai.azure.com",
           "deploymentId": "text-embedding-ada-002",
           "modelName": "text-embedding-ada-002",
         },
       }
     ]
    

程式化定義向量化器

如果你沒用過入口網站精靈,或想在現有索引中加入向量器,你可以用程式方式定義向量器和向量設定檔。 向量剖面將向量器與一個或多個向量場連結,並指定用於導航結構的向量搜尋演算法。

要在現有索引中定義向量器與向量剖面:

  1. 使用 Indexes - Get (REST API) 取得索引定義。 用你自己的值替換服務名稱、索引名稱和存取權杖。

    ### Get index definition
    GET https://my-search-service.search.windows.net/indexes/my-index?api-version=2026-10-01 HTTP/1.1
    Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-admin-api-key>
    

    Warning

    擷取到的自訂 Web API 向量器對每個 httpHeaders 值都包含 <redacted>。 當你更新同一個向量器而不更改其 name、 、 或 kind時,你可以重新提交uri以匹配現有<redacted>標頭名稱。 如果你更改 uri了,請為每一項 httpHeaders 提交實際數值。 關於其他更新規則,請參見 自訂網頁 API 向量器。

  2. 使用 Indexes - Create or Update (REST API)來更新索引定義。 將完整的索引定義貼上到請求文中。

    ### Update index definition
    PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2026-10-01 HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-admin-api-key>
    
    // Paste your index definition here
    
  3. 新增一個vectorizers區段到vectorSearch物件。 本節指定已部署嵌入模型的連線資訊。 以下範例包含 Azure OpenAI 與自訂網頁 API 作為比較。

    "vectorSearch": {
        "vectorizers": [
          {
            "name": "my_azure_open_ai_vectorizer",
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
              "resourceUri": "https://url.openai.azure.com",
              "deploymentId": "text-embedding-ada-002",
              "modelName": "text-embedding-ada-002",
              "apiKey": "<your-azure-openai-api-key>"
            }
          },
          {
            "name": "my_custom_vectorizer",
            "kind": "customWebApi",
            "customWebApiParameters": {
              "uri": "https://contoso.embeddings.com",
              "httpMethod": "POST",
              "authResourceId": null,
              "authIdentity": null
            }
          }
        ]
      }
    
  4. 新增一個 algorithms 區段到 vectorSearch。 本節定義用於導航結構的 向量搜尋演算法 。

    "algorithms": [
      {
        "name": "my_hnsw_algorithm",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ]
    
  5. 新增一個 profiles 區段到 vectorSearch。 本節將參考前述步驟中定義的向量化器與向量搜尋演算法。

    "profiles": [ 
      { 
        "name": "my_vector_profile", 
        "algorithm": "my_hnsw_algorithm", 
        "vectorizer": "my_azure_open_ai_vectorizer" 
      }
    ]
    
  6. 在陣列中 fields ,透過指定 vectorSearchProfile 性質,將向量剖面指派給一個或多個向量場。

    "fields": [
        ... // Trimmed for brevity
        {
          "name": "vector",
          "type": "Collection(Edm.Single)",
          "dimensions": 1536,
          "vectorSearchProfile": "my_vector_profile",
          "searchable": true,
          "retrievable": true
        },
        {
          "name": "my_second_vector",
          "type": "Collection(Edm.Single)",
          "dimensions": 1536,
          "vectorSearchProfile": "my_vector_profile",
          "searchable": true,
          "retrievable": true
        }
    ]
    
  7. 發送 PUT 請求以更新索引定義。 如果要求成功,您應該會收到 204 No Content 回應。

  8. 要驗證向量器與向量剖面,請從第一步重跑 GET 請求。 確認:

    • 陣列 vectorSearch.vectorizers 包含你的向量化器定義,並包含正確的 kind 設置和連接參數。

    • vectorSearch.profiles 陣列包含一個依名稱參照您的向量化工具之設定檔。

    • 陣列 vectorSearch.algorithms 包含了你個人資料所參考的向量搜尋算法。

    • 在 vectorSearchProfile 陣列中,向量欄位上的 fields 屬性會符合設定檔名稱。

測試向量化工具

要確認向量化器是否有效,可以發送一個向量查詢,傳遞文字字串而不是向量。 以下範例針對「 使用精靈定義向量器」中的範例索引,但你也可以透過調整欄位名稱和查詢參數來測試自己的索引。

使用 Documents - Search Post (REST API)來發送請求。 用你自己的值替換服務名稱、索引名稱和存取權杖。

### Test a vectorizer with a vector query
POST https://my-search-service.search.windows.net/indexes/vector-nasa-ebook-txt/docs/search?api-version=2026-10-01 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-query-api-key>

{
    "count": true,
    "select": "title, chunk",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "what cloud formations exist in the troposphere",
            "fields": "text_vector",
            "k": 3,
            "exhaustive": true
        }
    ]
}

重點:

  • "kind": "text" 告訴搜尋引擎輸入為文字串,並使用與搜尋欄位相關聯的向量器。

  • "text" 是要向量化的自然語言字串。

  • "fields": "text_vector" 是要查詢的欄位名稱。 如果您使用精靈所產生的範例索引,產生的向量欄位會命名為 text_vector。

  • "exhaustive": true 繞過 HNSW 圖,對所有向量執行暴力搜尋。 此設定有助於測試準確度,但速度較預設的近似搜尋慢。 在生產查詢中移除此參數以提升效能。

  • 查詢本身並未設定任何向量化器的屬性。 搜尋引擎會自動從分配給該欄位的向量輪廓中讀取這些資料。

若向量器設定正確,回應會回傳依相似度排序的相符文件。 你應該會得到三個結果(k: 3),其中第一個最相關。

{
    "@odata.count": 3,
    "value": [
        {
            "@search.score": 0.66195244,
            "chunk": "Cloud Shadow\tGermany\nIn November 2012, the Earth Observing...",
            "title": "page-25.txt"
        },
        ... // Trimmed for brevity
    ]
}

故障排除

如果你的矢量器沒有如預期運作,先從常見錯誤表開始,然後查看診斷日誌以獲得更詳細的資訊。

常見錯誤

下表列出常見的向量器錯誤及其解決方法。

錯誤 原因 解決辦法
驗證失敗 (401/403) 嵌入模型的 API 金鑰無效或缺少 RBAC 角色指派。 驗證您的 API 金鑰,或確認 Foundry IQ 服務識別在 Azure OpenAI 資源中具有該Cognitive Services OpenAI User角色。
尺寸不匹配 向量器模型產生的嵌入維數與向量場預期不同。 確保 dimensions 向量場的性質與嵌入模型的輸出維度相符(例如,1536 的 text-embedding-ada-002)。
速率限制 (429) 嵌入模型提供者正在限制請求。 檢視 Azure OpenAI 配額限制 ,並考慮增加每分鐘代幣(TPM)分配或減少批次大小。
找不到向量器 向量配置文件引用了索引中不存在的向量化工具名稱。 確認向量設定檔中的vectorizer屬性是否符合name陣列中的向量化器vectorizers。
空結果 文字轉向量轉換成功,但查詢未回傳任何匹配。 驗證 fields 向量查詢中的參數是否與可搜尋的向量場名稱相符。 增加 k 以獲得更多結果。

查看記錄

如果您為 Foundry IQ 服務啟用診斷記錄,請執行以下 Kusto 查詢以確認向量欄位的查詢執行。

OperationEvent
| where TIMESTAMP > ago(30m)
| where Name == "Query.Search" and AdditionalInfo["QueryMetadata"]["Vectors"] has "TextLength"

最佳作法

  • 在生產環境中使用管理身份(managed identity)代替 API 金鑰。 受管理身份更安全,避免金鑰輪換的負擔。 如需更多資訊,請參閱 「設定 Foundry IQ 服務以使用受管理身份連線」。

  • 將嵌入模型部署在與您的 Foundry IQ 服務相同的區域。 共置可降低延遲並提升服務間資料傳輸速度。 向量化器在所有有 Foundry IQ 的地區皆有提供,但模型供應情況因供應商而異。

  • 請分開部署相同的嵌入模型來進行索引和查詢。 專用部署讓你能獨立為每個工作負載分配 TPM 配額,並更容易辨識流量來源。

  • 監控你的 Azure OpenAI TPM 配額。 如果你達到 TPM 限額上限,請檢閱 配額限制,並考慮透過 技術支持案件申請更高的限額。

  • 查看 Azure OpenAI 嵌入技能的最佳實踐。 Azure OpenAI 向量器也適用同樣的指引。