在 Foundry IQ(Azure AI 搜尋服務)中遷移嵌入模型

Note

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

嵌入模型遷移會改變您的 Foundry IQ(Azure AI 搜尋服務)應用程式將文件與查詢以向量方式呈現的方式。 您可能會因為某個模型退役,或是您對相關性、語言覆蓋範圍、延遲、吞吐量、成本或資料駐留性的需求改變而進行遷移。 根據你的工作負載來評估替換模型,而不是假設新模型比較好。

本指南協助您選擇遷移方式、重新生成嵌入、驗證結果,以及切換生產流量。 對於大多數生產遷移,請建立並測試一個獨立的目標索引,同時保留現有索引。 您的原始資料、新鮮度需求、可用容量以及對中斷的容忍度,決定如何將資料填入至該目標索引並切換至該目標索引。

Prerequisites

  • 現有的向量或混合搜尋應用程式,包括其索引結構的存取權限、匯入設定及查詢設定。
  • 您可以重新處理的權威來源資料,或是遷移所需之索引內容的完整匯出。
  • 具有已驗證文件與查詢介面的替代嵌入模型部署。 對於 Microsoft Foundry 中的模型,請檢視目前的淘汰時程。
  • 管理索引及讀寫文件的權限,以及呼叫替換型號或自訂端點的授權。
  • 搜尋容量與遷移工作負載的模型配額,包括任何暫時的重複索引或向量欄位。
  • 具代表性的評估查詢、預期存取決策及業務驗收標準。
  • 同時變更來源、切換與回滾的計畫。

選擇移轉方法

首先,決定替換向量要儲存在哪裡,以及要從哪裡取得要嵌入的內容。

Approach 選擇何時 需求與取捨 成本考量
從來源資料重建獨立索引 你使用內建索引器,或需要來源資料重播或新的區塊化/擴充功能。 索引器管線新增索引與索引器;獨立驗證與來源變更追補。 完整語料庫嵌入、來源讀取、適用的付費豐富化,以及重複索引容量。
將匯出的索引內容重新嵌入到獨立索引中 您可以管理推送式擷取,並能完整匯出合適的文字或區塊。 驗證結構描述是否符合資格條件與匯出一致性。 這些樣本需要在備份時凍結寫入。 替換嵌入、匯出儲存空間、適配器託管及重複索引容量。
在現有索引中新增第二個向量欄位 您管理推送匯入,並希望在保留舊向量的同時分享內容。 新增欄位/設定檔、有界回填,以及協調寫入。 請參閱 第二欄位程序。 替換嵌入、重複向量、回填寫入,以及可能需要水平擴充。雙重寫入則增加了持續的嵌入工作。
替換現有欄位中的向量 你管理推送導入並接受受控的中斷。 不是生產預設。 相容的欄位定義與協調的讀寫器。 隔離混合嵌入空間;保留復原資料。 替換嵌入與寫入、復原相關資料,以及還原或重新嵌入。

對於分離索引程序,請使用前兩種方法,或在原地移轉時採用第二欄位程序。 覆寫現有欄位需要另行制定應用程式專用的復原計畫。 請參閱 「更新或重建索引」,以了解支援的結構變更,以及 範例工作流程 中目前與規劃中的範例涵蓋範圍。

如果 Foundry IQ 內建索引器填充您的索引,請使用 「從權威來源資料重建」。 此移轉路徑需要使用新的索引器,將完整來源資料重建到新索引中。 本指南中的匯出與相同索引替代方案是針對應用程式管理的推送擷取,而非現有索引器管線的原地移轉。

相同的備份與還原有助於練習復原,但不會遷移嵌入模型。 它只會複製現有的向量。

選擇如何處理同時變更

另外,決定如何在產生替換嵌入時保持內容最新。

Strategy 選擇何時 必要控制項 成本考量
暫停寫入 維護時段或新鮮度延遲是可以接受的。 停止相關的索引器、推送寫入器、更新、刪除及結構描述變更。 在恢復正常運作前,先考慮上游的變更。 在暫停期間避免同時生產新舊世代,但要預留預算以應付補上進度以及資料新鮮度延遲帶來的商業影響。
從一致的來源快照建立並重播變更 你需要很短的切換時段,並且具備持久性的變更串流。 追蹤起始浮水印,並重播建立、更新、刪除及權限變更。 正式切換前,先協調目標端。 快照儲存、變更擷取、重播與對帳。 反覆變更可能需要額外的嵌入。
維持舊有與新的導入路徑 持續的新鮮度足以證明額外的工程與容量。 為兩個索引或兩個欄位產生模型專屬向量。 協調對同一文件的寫入作業,並處理重試、部分失敗、刪除及權限變更。 兩種模型都會處理適用的變更。 加入額外的寫入次數、重試、保留容量以及對帳工作量。

這些選項屬於導入架構的選擇,而非自動遷移功能。 搜尋匯出不是具交易一致性的快照,且移轉樣本不會捕捉並重播同時進行的變更。 寫入兩個索引並不是一個原子操作。

對於一個索引中的兩個欄位,雙重寫入是指在每個變更的文件中讓兩個嵌入都維持最新狀態。 它不需要反覆嵌入整個語料庫。 使用有界回填,並控制進度與一致性。

對於內建索引器而言,平行擷取意指保留舊的管線,同時由新的索引器從來源填充新索引。 這並不代表要透過現有索引器回填第二個欄位。

讓查詢持續以舊索引為基準,並不一定能讓舊索引保持最新。 定義您的可用性需求以及可接受的資料延遲。

估算遷移成本

區分一次性回填成本、臨時重疊成本,以及穩態營運成本。 沒有任何方法總是最便宜:在同一個索引中共享文字與元資料減少重複,但兩個向量場仍會消耗向量容量。

  1. 建立目前的生產基準以及預期的遷移與回滾期間。 將額外的遷移支出與您已為現有應用程式所產生的成本分開計算。
  2. 在估算完整語料庫之前,先測量一個具代表性的試點。 記錄來源資料量、產生區塊數、提供者計費的嵌入使用量、重試次數、索引大小及處理經過的時間。 使用實際提供者的計費單位;不要以為每個模型都是以代幣計費。
  3. 估算 初始重建或回填時間。 包含替換嵌入、來源讀取或匯出、適用的解析與付費豐富化、工件儲存、介面卡託管及資料傳輸。 對於新的索引器來說,應該為完整的來源資料載入做預算,而不是假設舊的增益處理快取會消除這些工作。 處理失敗或重複處理仍可能產生費用。
  4. 估算臨時重疊與驗證。 包含任何額外的搜尋容量、變更內容的舊/新匯入、快取未命中與預熱、評估查詢、適用的高級查詢功能,以及回滾保留。 允許重試與一致性處理。 節流可能延長重疊期間,並增加按時間計費的資源成本。
  5. 估算 切換後的穩態成本。 將替換模型持續的文件與查詢嵌入使用量、搜尋容量、向量儲存及介面卡成本與基準進行比較。 只有在驗收並回滾視窗結束後才退休舊資源。

正確套用計費模式:

  • 專屬搜尋: 費用取決於預定容量以及您保留容量的時間長短。 第二個索引或向量欄位不會自動使 Search 費用加倍,也不會增加按索引、欄位或每次寫入收取的費用。 檢查現有容量是否能應付高峰工作負載;額外的複本、分割區或其他服務可能會增加成本。 模型呼叫與其他計費服務則維持分開。
  • 無伺服器搜尋(在支援的情況下):運算與索引儲存則依使用量計費。 包含索引與查詢工作,而不只是儲存向量。 請檢查目前的 層級限制與網路限制 ,而非假設所有遷移情境皆支援。

請使用 搜尋成本指引、 容量規劃及目前 Foundry IQ 的定價。 從所選部署的定價資訊中取得模型費率。 設定預算與警示,監控遷移期間的實際使用情況,並在擴充工作負載前調查意外重處理情況。

刪除舊向量後,請檢查您是否能在符合工作負載需求的同時減少複本或分割區。 僅靠儲存空間清理無法降低專用搜尋費用。 將任何剩餘的工件或快取保留納入遷移後的預算中。

定義替代嵌入規格

對於每個向量欄位,記錄索引與查詢必須共同使用的設定:

  • 模型識別碼、版本、部署、端點及 API 合約。
  • 輸出維度以及適當的相似度指標。
  • 輸入預處理、區塊化、截斷與正規化。
  • 在需要時,提供提供者專屬的文件與查詢任務設定。
  • 驗證、網路存取及區域可用性。

更改向量器或部署名稱不會重新產生已編入索引的向量。 若要變更嵌入空間,請從預期的文字、圖片或其他來源輸入重新產生文件嵌入。 相等的向量維度並不能證明模型間的相容性。

保持每個向量欄位與用來產生查詢向量的模型相容。 不同模型可以共存於不同的欄位或索引中。 若要整合向量化,請選擇 支援的技能與向量化器組合。 如果替換程式需要自訂介面卡,請同時驗證其 編製索引技能 與 查詢向量器 契約。

如果你也改變了區塊,建議在可行的情況下分別比較這些變更,這樣你才能區分該變更的影響與模型變更的影響。 檢視壓縮與相似度設定,而非假設為舊模型調整的設定仍然適用。

在遷移期間處理快取

盤點擷取與查詢路徑中的快取。 切換模型、向量欄位或索引別名並不會自動使應用程式管理的快取失效。

  • 索引器豐富快取(預覽): 此快取屬於其索引器,而非應用程式查詢路徑。 不要以為你可以把它轉移到新的索引器上。 遵循 再處理的相關考量;快取的舊模型向量並不能取代產生新的嵌入。
  • 應用程式管理的文件嵌入: 只有當該條目的輸入內容與嵌入合約相符時,才可重複使用。 在快取金鑰中包含原始版本或內容雜湊值及合約版本。 變更區塊或預處理可能會使先前快取的嵌入失效。
  • 應用程式管理的查詢嵌入: 依查詢輸入與嵌入合約作為鍵建立條目,而非僅以查詢文字為依據。 部署名稱或端點在其模型變更期間可以保持不變。 在提供者要求時,將文件與查詢工作設定分開。
  • 應用程式管理的搜尋結果或答案: 考慮目標索引產生、向量欄位、查詢設定、篩選條件及授權上下文。 當來源內容或權限變更時,使受影響的條目失效。 除非請求使用者目前的存取權仍然有效,否則不要提供快取內容。

使用明確的嵌入合約版本,涵蓋模型識別/版本、維度、任務設定及預處理。 在並行期間與回滾期間,保持舊版與新版應用程式快取命名空間分開。

如果模型在自訂技能端點後發生變更,卻沒有明顯的技能組變更,快取輸出可能會保持陳舊狀態。 遵循文件中記錄的 技能失效與再處理程序,針對受影響的技能及其依賴關係進行。 此程序不會取代索引器遷移路徑所需的 new-indexer 來源重建。

為快取儲存、未中時的替換模型呼叫,以及預熱流量進行預算。 切換前測試冷路徑與暖路徑;暖快取不應隱藏不相容的模型、過時的文件或錯誤的存取決策。

Cohere Embed v3 停用規劃

Foundry 模型退休排程將 2026 年 11 月 15 日列為 Cohere-embed-v3-multilingual 和 Cohere-embed-v3-english 的棄用日期。 兩個模型都將於 2027 年 2 月 15 日淘汰。 列出的替換項目為 Cohere-embed-v5-fastCohere-embed-v5-pro和 。 規劃移轉時,請查看更新時程。

在退休前完成並測試遷移,留出時間解決故障並練習回滾,趁舊模型仍可用。

  1. 識別使用任一淘汰模型的擷取管線與查詢路徑,包括用戶端查詢嵌入產生。
  2. 根據具代表性的查詢,以及您的品質、延遲、吞吐量、語言與成本需求,評估替換模型。 在 Microsoft Foundry 中部署所選的替代模型,並驗證其文件與查詢介面以及輸出維度。
  3. 選擇 一種遷移方式。 內建索引器管線需要完整重建來源資料,並新增新的索引與索引器。 對於推送擷取,建議設定獨立的目標索引,或新增第二個具有一致性控制的欄位。 重新生成文件向量;不要複製 v3 向量,只更改查詢模型。
  4. 若要使用 Python 或 .NET 範例進行推送匯入,請設定所選fast或pro模型及已驗證的嵌入函數。 這些範例使用自訂 Web API 向量器;Foundry 中列出的替代項並不代表現有的原生搜尋技能或向量器已支援該替代項。
  5. 完成 資料、存取與檢索測試,然後 切換流量。 同時更新正在進行的資料匯入與查詢嵌入產生。

選擇 v5 版本

請根據您測試的工作負載選擇變體,而非僅僅模型名稱。 有關功能與工作負載指引,請參閱 Microsoft Foundry 中的 Cohere Embed V5。

Variant 工作負載優先順序 範例部署名稱
快速嵌入 v5 延遲敏感的互動式搜尋與響應式代理體驗。 cohere-embed-v5-fast-sls
Embed v5 Pro 優先尋找最相關資訊的應用中,檢索品質。 cohere-embed-v5-pro-sls

Fast 和 Pro 共享嵌入空間,但這種相容性不適用於現有的 v3 向量。 重新產生 v3 文件嵌入以進行 v5 遷移。 驗證所選配置的維度、文件/查詢任務設定、相關性、延遲與成本。

呼叫 Cohere 提供者端點

直接的 Cohere 嵌入請求使用此端點模式: POST https://<foundry-resource>.services.ai.azure.com/providers/cohere/v2/embed。

請用你的 Foundry 資源名稱替換 <foundry-resource> 。 將請求 model 值設定為您已部署模型的部署名稱,例如 cohere-embed-v5-fast-sls 或 cohere-embed-v5-pro-sls。 兩種變體都使用相同的供應商路徑。 前表中的名稱僅為範例,並非必備的部署名稱。

請依照請求負載、API 版本及驗證設定的 遷移範例 操作。 索引時使用文件任務,產生查詢向量時使用查詢任務。

此提供者端點並非搜尋自訂 Web API 向量器端點。 在範例工作流程中,保持向量器指向已驗證函數的查詢路徑。 此函數會將搜尋請求調整為 Cohere 提供者請求。

準備目標資料與來源資料

在開始移轉之前,請先準備好設定與一致性控制項。

  1. 盤點您的索引欄位、文件鍵、父子關係、向量設定檔、壓縮、分析器、語意配置與評分設定檔。 識別應用程式、索引器、知識來源及其他依賴它們的取用者。
  2. 建立包含來源與目標索引或向量欄位名稱、嵌入合約、預期結構變更、同步策略及接受條件的遷移記錄。
  3. 設定目標授權與網路存取。 區分遷移運算子、呼叫嵌入端點的搜尋身份,以及呼叫模型的任何中介身份。 成功的本地模型呼叫並不能證明搜尋具有存取權限。
  4. 為您的遷移設定寫入凍結、來源快照或變更重播邊界。
  5. 定義目標綱要。 若要進行獨立索引遷移,請預留新的索引名稱,並透過您所選的工作流程建立該索引。 在範例的匯出與還原工作流程中,保持目標不存在:還原會建立目標並拒絕覆寫現有索引。 對於第二個欄位的遷移,請先規劃對現有架構的新增內容。

不要為了騰出空間而刪除生產索引,除非另有一套經過審核的可用性與復原計畫。 以符合來源內容的存取控制與保留政策保護匯出文件與遷移產物。 不要將它們提交到原始碼儲存庫。

由 GET 或 LIST 回傳的索引定義並非憑證備份。 重新建立所需的相依關係,並明確提供目標驗證資訊。 關於索引管理工作,請參閱「管理搜尋索引」。

保留文件識別資訊與存取控制

將文件識別資訊及其相關內容、中繼資料和權限整合在一起。 如果分塊或金鑰產生變更,請考慮過時的父記錄與子記錄,而非假設新寫入會移除這些記錄。

對於受保護的內容,請保留提供權限的支援連接器或受信任的擷取流程。 複製具有類似權限名稱的欄位不會重建連接器衍生的權限來源。 在選擇匯出推送遷移前,請確認您的 文件層級存取流程 需求。

不要假設一般的遷移範例都支援所有已啟用權限或產生的知識來源索引。 若無法建立受支援且完整的傳輸,請透過適當的來源擷取流程重建。 在將目標暴露給應用程式之前,先驗證有效存取。

檢查匯出資格

如果您是從現有索引而非權威來源資料遷移,請勾選重建文件所需的所有欄位。

  • 您必須能夠取得所需的內容。 索引匯出無法還原它無法讀取的原始文字或中繼資料。
  • 你無法透過 stored: false 文件檢索恢復向量。 更改 retrievable 不代表它們可以匯出。
  • 樣本的分頁需求必須與關鍵欄位及語料庫大小相符。 Python 和 .NET 的分頁資格規則並不完全相同。
  • 匯出時必須包含完整的預期文件集,而非僅僅包含受限制的查詢身分可見的文件。

對於具有已儲存內容的欄位,變更可擷取性可能會受到支援,但這也會改變查詢可回傳的內容。 不要為了滿足樣本而廣泛暴露敏感欄位。 請參閱向量儲存選項,以了解 retrievable 與 stored 之間的區別。

產生並載入替換嵌入

依照您所選方法的程序操作。 在替換項目通過驗證之前,將生產讀取保留在現有索引和舊向量欄位上。 只有為替換嵌入合約所設定的攝取路徑,才應寫入替換向量。

從權威來源資料重建

請使用此流程用於 Foundry IQ 內建索引器。 當來源資料與元資料可重播,或解析、分塊或豐富化必須變更時,也將它用於應用程式管理的匯入。

對於基於索引器的遷移,變更現有的向量器或模型部署不會回填替換嵌入。 建立一個新的管線,用來處理完整的來源語料庫。 保留現有索引與管線,直到替代項目通過驗證。

如果替換模型沒有支援內建嵌入技能與向量器配對,請保留內建索引器,並在新管線中新增自訂整合:

  • 索引: 將 自訂 Web API 技能 加入新技能組合。 其端點會使用替換模型產生文件嵌入。 視情況,透過輸出場映射或索引投影,將其輸出映射到新的向量場。
  • 查詢: 在新索引中設定 自訂 Web API 向量器 ,並透過向量欄位的設定檔來參照。 其端點可為文字向量查詢產生相容的查詢嵌入。 如果你的應用程式直接傳送查詢向量,請更新其嵌入產生器。

實作符合技能與向量器請求與回應合約的適配器端點。 除非該 API 實作所需的搜尋合約,否則不要將任一元件指向原始模型 API。 對兩條路徑使用相同的替換嵌入合約,並設定適當的文件與查詢任務設定。

分別設定搜尋至介面卡與介面卡至模型呼叫的身分驗證與網路存取。 在開始完整載入前,透過實際的 Search 身分識別驗證文件嵌入產生與查詢向量化。

  1. 建立新的目標索引,使用替換的向量欄位與設定檔。 將生產查詢保留在現有索引上。
  2. 如果在某個技能集中產生嵌入,請為替換模型建立獨立的技能集,並檢視其指數預測目標。 不要以某種方式改變共用的生產技能組合,讓舊的流程切換到新模型。
  3. 使用替代合約設定文件嵌入產生與查詢向量化。 保留與相應文件及區塊相關聯的來源權限。 針對基於索引器的整合向量化,請參考「設定整合向量化」。 對於應用程式產生的向量,請依照 「產生嵌入向量」操作。
  4. 對於內建索引器, 請建立一個新的索引器 ,包含其來源連線、新的目標索引、在適用時的替換技能組合,以及欄位/輸出對應。 在設定期間,將 disabled 設為 true;否則,建立作業會立即開始執行。
  5. 在開始全負載前,先驗證具代表性的測試負載。 對於內建索引器,請使用具有有限來源範圍的獨立測試管線。 請讓完整來源移轉索引器維持停用,直到準備好進行完整負載。
  6. 透過新管道處理完整語料庫。 對於內建索引器,請 規劃重新處理、啟用並執行移轉索引器,並 監控其執行歷史、錯誤與警告。 對於推送匯入,請檢查每份文件的索引結果。 在宣告載入完成前解決失敗。
  7. 套用同步計畫所需的來源變更,包括刪除與權限變更。

當目標語料庫載入且透過您約定的同步點進行變更時,即可準備好接受驗收測試。

規劃索引器重新處理

完整的來源重建不僅僅是將文件複製到新索引中。 規劃初始處理工作、後續變更,以及從中斷執行中恢復。

  • 初始載入: 新的索引器擁有自己的處理狀態。 針對整個預期語料庫,規劃來源資料讀取、解析、分塊、適用的豐富化與替換嵌入的預算。 在此載入前先設定替換模型;不要等到原始文件變更後才重新生成向量。
  • 增量式執行: 初始載入後,一般執行會使用來源所支援的變更偵測行為。 它們不是要求你重新生成每一個向量。 在依賴新索引的排程前,請先確認更新、刪除與權限變更如何反映到新索引中。
  • 豐富快取:豐富快取是預覽功能,由索引器管理。 不要假設舊索引器的快取會轉移到新管線,或讓重建是增量式的。 當模型輸入或技能行為改變時,請遵循 快取處理指引 。
  • 重試與重置: 不要假設每個區塊只處理一次或只呼叫一次模型。 中斷與重試可能重複工作,並消耗模型配額與預算。 執行並監控遷移索引器 以繼續處理;不要例行重設或重建它來重試失敗。 重置後執行會要求完整重新處理。
  • 區塊與刪除的一致性檢查: 如果解析或分塊有變化,重處理可能會改變區塊數或鍵值。 檢查缺失或過時的子記錄,並保留其正確的權限。 重設並重新執行不會移除來源紀錄已不存在的孤立文件;使用支援的刪除流程。
  • 管線重疊: 在兩個索引器都持續運作時,來源變更可能會同時啟動兩種模型及適用的豐富化。 將這些重疊、節流以及重複作業納入 遷移成本估算中。

Enrichment 快取不是備份,也不是記錄遷移完成狀態的清單。 反覆中斷或技能執行失敗會增加大型來源的再處理次數。 在假設快取能降低重建成本或持續時間之前,先驗證具代表性的工作負載。

在同一索引中新增第二個向量欄位

請將此流程用於應用程式管理的推送擷取,而非內建索引器管線。 索引器使用者必須 使用新的索引器從來源重新建立。

在填充並測試替換項目時,將舊的和新的向量欄位放在一起。 這種做法避免建立第二個完整索引,但回填會與生產流量競爭,且無法保證服務不中斷。

  1. 確認您的匯入流程支援結構與寫入變更。 不要以為生成的知識來源索引就支援任意自訂。 在撰寫任何文件前,檢查兩個向量集的容量並檢視 部分更新風險 。
  2. 新增向量場、相容的向量配置檔、演算法配置,以及適用時的向量化器。 使用替換模型的維度與相似度設定。 現有文件在新欄位中的值一開始為 null。
  3. 將生產查詢保留在舊的向量欄位與相容的查詢模型上。 為新文件與變更文件設定寫入暫停或協調雙重寫入。 在雙重寫入時,從同一權威內容版本產生兩個嵌入,並明確處理失敗。
  4. 為每份現有文件,從指定文字回填新欄位。 使用 Make backfill bounded and restartable 中的控制項。 保留無關的內容、權限及舊向量。
  5. 透過約定的同步邊界,核對所有預期的文件金鑰與來源修訂。 解決遺失的向量、寫入失敗、刪除及權限變更。 僅僅匹配文件數量並不能確定覆蓋範圍。
  6. 在切換生產查詢前,完成對新欄位的 資料存取與檢索測試。
  7. 在保留約定的回滾視窗的舊路徑的同時,切換相同索引的查詢路徑。 在該時段內保持舊向量的最新狀態,或維持經過測試的追趕路徑。
  8. 在回滾視窗結束並完成驗收後,停止產生舊的嵌入。 可選擇性地透過經過測試的文件更新流程清除舊向量值。 舊欄位會保留在結構中,直到您重建索引。

不要嘗試透過在原地更改 searchable 舊欄位的屬性來停用舊欄位。 變更該屬性或移除欄位需要重新建立。 保留欄位定義並不需要查詢它。

讓回填有範圍限制且可重新啟動

將歷史回填與持續攝取分開。 先處理一次初始語料庫,透過持續流程處理新內容和變更內容,並在切換前進行對帳。 持續的原始碼變更可能需要多一次協調輪次。

使用進度追蹤以避免不必要的嵌入呼叫,並透過撰寫者協調來避免過時的更新。 這些由應用程式管理的控制項解決了不同的問題。

控制 如何使用 Limitation
遷移版本與準備狀況 追蹤新向量所使用的嵌入合約版本及原始碼修訂版本。 處理遺失或過時的工作;只有在向量寫入成功後才記錄完成。 像布林值這樣的布林 vectorV2Ready 值,單獨無法證明在來源變更後仍然新鮮。 標記不是鎖。
確定性檢查點 為有限次處理持續保留穩定的可排序/可篩選鍵檢查點或權威來源游標。 在宣告本輪處理完成前,保留失敗的金鑰以供重試。 文件金鑰並不自動成為建立時間標記。 游標後方的新紀錄或已修改紀錄需要重播或對帳。 搜尋分頁並不是交易快照。
原始碼修訂或內容雜湊 將向量所使用的內容與嵌入契約與當前來源狀態進行比較。 跳過已是目前狀態且未更改的紀錄。 在寫入前做修訂檢查並不會阻止檢查與寫入之間的變更。 將所有嵌入輸入與預處理納入比較中。

將進度儲存在外部耐用帳本或合適的索引欄位中。 如果您以索引標記進行篩選,請為這些查詢設定其欄位類型及可篩選性。 當向量寫入還在等待中或失敗時,不要標記為工作完成。

協調每個文件索引鍵的歷史與持續寫入者。 例如,讓兩者都經由同一個 ingestion owner 處理,由其將變更序列化並拒絕過時的來源修訂版本。 單靠一個標記無法阻止舊的嵌入請求在新寫入後完成並覆寫它。

不要依賴批次動作排序、對未變更的過時負載的重試,或假設的文件層級條件更新保證。 如果你無法建立可靠的順序與協調,請使用寫入暫停或獨立索引方法,並搭配適當的同步計畫。

對於現有紀錄的歷史更新,請考慮 merge,當記錄不再存在時,該更新會失敗。 過時的 mergeOrUpload 或 upload 可能會重新建立已刪除的記錄。 以相同的擷取流程協調刪除與權限變更,並檢查每份文件的索引結果。

使用遷移範例

以下參考範例示範如何重新嵌入匯出的文字到新的目標索引中。 請依照各自的 README,查看相依性、身分驗證、設定、命令和驗證。

這些範例使用應用程式管理的推播工作流程。 它們並不是現有內建索引器管線的遷移工具。 對於內建索引器,請依照完整來源重建程序,使用新的索引與索引器。

Sample 匯出式工作流程 同索引第二欄工作流程
Python 嵌入模型遷移 備份符合條件的凍結來源索引,驗證相同的還原,重新生成所選向量欄位,並還原到新的目標。 包含嵌入函數及可選的 Blob 擷取管線範例。 預計在此範例位置提供。 依照 第二欄程序操作;請查看 README 以了解可用的實作。
.NET 嵌入模型遷移 使用備份/還原工具建立完整基準,準備重新嵌入的工件,並可選擇將其還原到新目標。 使用獨立部署的嵌入函數。 已規劃於此範例位置。 依照 第二欄位程序操作;請查看 README 以了解可用的實作。

基於匯出的工作流程使用經驗證的文件與查詢嵌入路由。 fast 和 pro 的選擇是針對特定範例的模型配置,而非適用於任意供應商的通用開關。 針對替換模型的實際介面驗證任何調整。 他們的程序如下:

  1. 檢視所選範例的架構、金鑰、儲存空間及驗證先決條件。 在雲端操作前執行離線檢查。
  2. 在備份期間凍結所有相關的來源寫入器。 命令列認可不會停止索引器或其他應用程式。
  3. 在全新輸出目錄中建立完整的基準。 拒絕部分匯出或不完整的工件作為遷移輸入。 如果你之後恢復來源端寫入,請在切換前擷取並重播這些變更。
  4. 驗證嵌入函式的文件與查詢路徑,包括身分驗證與測得的輸出維度。
  5. 產生替換向量並載入新的目標索引。 依範例要求使用新的工件目錄與目標名稱。 將非零退出及單文件失敗視為失敗,而非完成。
  6. 設定未來的導入以產生相容的向量。 範例不會自動遷移您現有的索引器、資料來源、技能集、別名或外部模型資源。

基於匯出的範例會從一個頂層文字欄位重新生成一個選取的頂層向量欄位。 不要以為這些元件會處理巢狀或多模態欄位、所有權限流程或任意投影架構。 它們也會改變所選向量輪廓的壓縮設定。 檢視目標的演算法與儲存設定。

可選的 Python 管線是一個完整文件的 Blob 範例,而非您現有的分塊、投影或安全性設定的重建。 只有當其擷取合約符合您的需求時才使用。

驗證資料、存取與檢索

在切換生產流量前,要求完成成功遷移測試。 在開始前先定義通過條件,使用適合您業務的門檻,而非依賴文件數量或一次成功的查詢。

分階段測試:先從一個小型、具代表性的資料集開始,驗證已完整填入的目標,然後反覆練習切換與回滾。 針對預期流量執行負載測試。 離線範例測試有助於檢查工具的行為,但無法取代針對您已部署模型、身分識別、網路組態和應用程式所進行的端對端測試。

檢查資料與設定

  • 將目標結構與預期變更進行比較。 檢查無關欄位、設定檔及相依關係,尋找意外差異。
  • 透過約定的同步點調和文件鍵、父子關聯、預期非向量值、刪除值及時效性。
  • 檢查替換向量是否已填入、為有限值,且符合預期維度。 解決上傳失敗及嵌入遺失的問題。
  • 確認新文件與更新均使用取代嵌入向量契約。
  • 對於索引器重建,請確認完整的初始原始碼載入、後續變更偵測,以及從中斷執行中恢復的情況。 將投影區塊與來源刪除對帳,而不是把索引器重設當作清理。
  • 對於第二欄位遷移,請確認準備度是否對應於目前的來源修訂與嵌入合約,而非僅為已填充的向量。
  • 對於應用程式管理的回填,請中斷並恢復處理。 確認已提交進度會跳過已完成且未變更的工作,且失敗記錄仍可重試。 未完成的工作可以重新執行;不要把這當成恰好一次保證。
  • 在歷史嵌入請求執行期間測試更新與刪除。 確認過時的作業無法覆蓋現有向量、無法錯誤標記為就緒,或重建已刪除的內容。
  • 測試紀錄在檢查點之後新增或變更。 驗證舊向量與權限的一致性核對與保存情況,包括適用的 stored: false 更新。

對於相同的基準副本,請比較內容保真度,包括向量。 對於模型遷移來說,舊向量和新向量不預期會在數值上相等。

檢查存取權與查詢執行

  • 使用具代表性的受保護內容測試授權與未授權身份。 保留支援的權限流程;不要用未經過濾或升級的備用方案取代。
  • 透過實際的搜尋身分與網路路徑測試查詢時向量化。
  • 驗證用戶端產生的查詢向量、所選欄位、設定檔及嵌入快取。 測試使用冷快取與暖快取(包括內容與權限變更) 進行快取失效與版本控制 。
  • 測試應用程式與相依的擷取取用端,而非僅直接向目標索引提出請求。

評估品質與營運

  • 將相關性與已判定查詢及業務任務進行比較,包括重要語言、篩選條件及查詢類型。
  • 測試您的應用程式所使用的向量、混合及語意查詢行為。 檢視基於分數的門檻,而非假設原始向量分數在不同模型間可比較。
  • 在具代表性負載下,測量延遲分布、吞吐量、節流、儲存與嵌入使用情況。
  • 確認目標符合您的新鮮度、可取得性、品質及營運預算需求。

如果檢查失敗,請在解決原因的同時,讓生產流量維持在現有路徑上。 不要僅因為完整負載已完成就切換。

切換流量並保留回滾路徑

在擷取與查詢過程中協調變更。 當應用程式產生查詢向量時,僅切換索引名稱是不夠的。

  1. 達到約定的寫入或變更重播界限,並完成驗收測試。
  2. 若要進行直接索引切換,請將應用程式的索引目標、查詢嵌入設定、選取的向量欄位與快取以協調一致的方式一併切換。 若要進行別名式切換,請依照「切換帶有別名的次要索引」操作;不要把別名和模型的變更當成原子層級的。
  3. 針對基於索引器的遷移,請保持新索引器針對新的實體索引,並依需要設定其持續排程。 透過其支援的目標設定更新知識來源。
  4. 確認生產環境的讀寫是否到達預定的目標端。 測試新文件、更新、刪除及適用權限變更。
  5. 在回滾時窗期間監控已同意的相關性與運作訊號。
  6. 只有在驗收與保留要求達成後,才會淘汰過時的攝取路徑與模型相依關係。 若要進行獨立索引遷移,請停用舊索引。 對於第二欄位遷移,請保留主動索引並遵循 舊向量清理指引。

保留相容的查詢路徑以及舊的索引。 如果舊模型退役或無法存取,僅靠舊索引可能無法提供可用的回滾。 趁舊模型還在時,先練習回滾。

在重新導向流量之前,先處理切換後接受的寫入。 回滾別名並不會把那些寫入資料複製到舊索引。

切換相同索引的查詢路徑

對於第二個欄位的遷移,請保留索引名稱並變更應用程式的查詢設定。 索引別名不會選取向量欄位。

  1. 完成新欄位的驗收測試與最終核對。
  2. 切換 vectorQueries.fields 到新的向量場及其相容的查詢嵌入模型。 對於文字向量查詢,請驗證與新欄位設定檔相關聯的向量化器。 更新快取及所有相依的查詢路徑。
  3. 測試生產讀取及持續寫入,包括更新、刪除及權限變更。 在回滾視窗期間,繼續維持這兩種嵌入路徑,或保留已測試過的方法來追趕舊欄位。
  4. 如果需要回滾,請使舊欄位與目前資料一致,並同時還原其相容的查詢設定。 舊模型必須仍然可用。
  5. 在驗收完成且回滾視窗結束後,退役舊模型寫入並執行任何預定的舊向量清理。

清除舊向量會移除那條立即回滾路徑。 使用實際的向量集合類型、API 及更新行為測試清理,並保留新欄位及無關內容。 物理上的消失並非立即發生;在重新評估容量前,先監控索引統計資料。

使用別名切換次要索引

如果您的應用程式已經使用 索引別名,請在重建索引時保留該別名名稱。 在同一 Foundry IQ 服務上建立並驗證次要索引,然後更改別名對應以指向該次索引。 支援的應用程式呼叫仍會使用相同名稱,且不更改其索引名稱參照。

  1. 確認應用程式支援的文件操作參照別名,而非實體索引名稱。 如果使用實體名稱,請先設定其使用別名,再依賴基於別名的切換。
  2. 在別名仍指向現有索引時,建立、填充並測試次要索引。
  3. 暫停特定模型的查詢,並暫停使用該別名的寫入端。 先排空進行中請求與排隊重試,然後完成最終同步。
  4. 更新現有別名 ,以以次級索引取代其索引目標。
  5. 更新後請保持流量暫停至少 10 秒,以允許別名傳播。 為替換索引設定用戶端嵌入、選取的向量欄位及快取。 在恢復查詢與推送寫入之前,透過別名驗證請求。 若驗證失敗,請保持流量暫停。

別名更新可能需要長達 10 秒才會生效。 立即切換用戶端產生的嵌入,可能會在該區間將替換模型向量傳送到舊索引。 回滾別名時,套用相同的暫停、耗盡、傳播等待與驗證序列。

如果你無法暫停流量,請使用應用程式路由,將每個查詢或每次推送寫入作業固定到實體索引及其相應的版本化嵌入配置。 在重試時保持這種配對。 不要依賴可變別名來原子切換索引與用戶端生成的嵌入。

別名範圍只適用於某個 Foundry IQ 服務。 如果目標索引位於不同服務上,請分別更新應用程式的服務端點;別名無法跨服務重新導向請求。

別名一次對應到一個索引;它不會在舊索引與新索引間分配請求,也不會在資源間提供交易。 它也不會重新生成向量或改變應用程式的嵌入模型。

索引器和 Foundry IQ 索引知識來源不能將別名作為目標。 請分別更新這些具體索引參考。

考慮同一索引遷移風險

若採用相同索引方法,請在回填時隔離舊嵌入與新嵌入空間,並驗證查詢如何處理遺失向量。 變更維度或其他欄位屬性可能需要新增欄位或索引,而非原地更新。

在回填前檢視部分更新行為。 對於具有 stored: false 的既有向量欄位,若在適用的 merge 或 mergeOrUpload 更新中省略向量,可能會遺失向量資料。 請參閱 向量儲存選項。

此風險適用於填寫新欄位或稍後清除舊欄位時。 保留或重新產生更新作業所需的所有受影響的向量。 如果您的匯入流程無法做到,請採用不同的遷移方式。

在覆寫現有欄位時,請將復原資料保留在該欄位之外,並在整個替換過程中隔離不相容的查詢。 新增第二個欄位保留舊向量,但仍需一致性控制、存取驗證及經過測試的回滾計畫。

針對遷移問題進行故障排除

徵兆 Action
匯出失敗或缺少必填欄位。 檢查可檢索性、向量儲存、查詢授權以及樣本的分頁需求。 如果無法完整匯出,請從原始碼重新建立。
向量生成或查詢會回報維度錯誤。 測量替換模型的輸出,並同時檢查欄位定義、設定檔與查詢產生器。 除非模型明確支援這種配置,否則不要填充或截斷向量。
文件數量相符,但內容過時或缺少紀錄。 透過同步邊界調和鍵值與欄位值。 檢查匯出或回填期間的刪除與變更。
回填會反覆嵌入未變更的文件。 透過嵌入合約版本與來源修訂版本來追蹤成功的工作。 檢查檢查點持續性、失敗鍵重試,以及缺少或過時的標記選取。
即使紀錄標示為「就緒」,新的向量仍然過時。 針對每個鍵協調歷史與持續寫入程序。 標記無法防止過時的寫入。 在切換前,先與目前的來源端修訂版本進行對帳。
刪除的記錄會在回填時重新出現。 防止過時的 upsert 重建已刪除的內容。 將刪除與回填協調,並考慮需要現有文件的更新。
函式在本地運作,但搜尋查詢失敗。 驗證 Search 到 Function 的驗證、受眾、呼叫者授權、網路存取及 Function 與模型的連線。 請參閱 自訂 Web API 向量器。
只有部分文件能成功載入。 檢視每份文件的結果、解決錯誤,並依照您的擷取計畫重試。 如需以索引器為基礎的載入,請參閱索引器疑難排解。
存取決策與來源不同。 不要讓目標進入正式環境。 在重新測試代表性識別前,請先檢視支援的權限匯入流程並記錄關聯。
檢索品質會退化。 檢查模型一致性、任務設定、預處理、分塊、相似度指標與壓縮。 在變更生產流量前,請先用具代表性的查詢重新評估。