FAISSCompatible with Milvus 3.0.0+

FAISS 索引類型是 Milvus 3.0.0 及後續版本中提供的一種專家級直通功能。它允許您提供Faiss 索引建立函式字串，而非選擇固定的 Milvus 索引類型。

當您已擁有經過測試的 Faiss 配方，且需要直接控制其組成時，請使用FAISS 。對於具有專用 Milvus 索引類型的常見配方，建議優先選用專用類型，因為它具有穩定且有文件記載的參數規範。

限制

• FAISS 支援FLOAT_VECTOR 和BINARY_VECTOR 字段。不支援FLOAT16_VECTOR 、BFLOAT16_VECTOR 、INT8_VECTOR 或SPARSE_FLOAT_VECTOR 字段。

• 通用型FAISS 適配器在 CPU 上運行。它並非 Faiss GPU 索引類型。

• 必須指定faiss_index_name 建置參數。Milvus 會將其值傳遞給 Faiss，而不會將配方轉換為專用的 Milvus 索引類型。

• 建置與搜尋參數因工廠而異。某個工廠支援的參數，可能被另一個工廠拒絕。

• 標量篩選需要底層的 Faiss 索引支援 ID 選擇器。Milvus 3.0.0 的測試涵蓋了使用浮點數工廠Flat 、IVF64,Flat 及HNSW16,Flat 進行的篩選搜尋。請勿假設每個工廠都支援篩選功能，亦請勿假設二進位FAISS 索引支援標量篩選。

• 不支援搜尋迭代器。

• 此適配器不提供原始向量檢索功能。

• 範圍搜尋（Range-search）的支援程度取決於工廠。浮點數Flat 已包含在發行版中。請勿在二進位FAISS 索引上使用範圍搜尋。

• 工廠即使能成功建置，仍可能拒絕某些 Milvus 搜尋操作。例如，獨立模式的PQ8x4 會拒絕標量篩選搜尋所使用的選擇器。請另行驗證未經篩選的使用情況。

• 在 Milvus 3.0.0 中，請於索引重新載入後驗證COSINE 的分數及範圍搜尋閾值。Knowhere v3.0.6 在反序列化過程中，無法還原FAISS 適配器的餘弦正規化狀態。

運作原理

FAISS 索引直通工作流程

在建立索引時，Milvus 會將 `faiss_index_name`、向量欄位類型、度量標準及其他建置參數轉發至 Knowhere FAISS 轉接器。該轉接器會針對 `FLOAT_VECTOR ` 欄位呼叫 `faiss::index_factory() `，或針對 `BINARY_VECTOR ` 欄位呼叫 `faiss::index_binary_factory() `。產生的物件為原生 Faiss 索引，並透過標準的 Milvus 索引生命週期進行管理。

在搜尋時，此轉接器會將提供的工廠特定參數轉換為對應的 FaissSearchParameters 物件。對於受支援的浮點數工廠，它還會將 Milvus 篩選器位元集作為 Faiss 選擇器傳遞。 選擇器的支援程度因工廠而異，且已發布的測試並未針對二進位FAISS 索引建立標量過濾機制。這正是為何某個配方在獨立運作的 Faiss 中可能有效，卻會因不符合 Milvus 搜尋路徑所需的操作而遭拒絕。

先決條件

• Milvus 3.0.0 或更新版本
• PyMilvus 3.0.0 或更新版本
• 熟悉 Faiss 索引工廠的語法，以及所選工廠的訓練要求

有關安裝說明，請參閱《安裝 PyMilvus》。

選擇工廠字串

工廠字串將 Faiss 索引描述為一組元件的序列。以下範例已通過 Milvus 3.0.0 版本的測試覆蓋率驗證。此清單並非詳盡無遺。

COSINE 條目顯示建置與搜尋的煙霧測試覆蓋率。對於 Milvus 3.0.0，這些測試並未驗證索引重新載入後分數或範圍搜尋的正確性。請參閱「限制」。

建置與搜尋浮點數索引

以下範例建立 3,000 個 128 維向量。這為範例中使用的IVF64,Flat 配方提供了足夠的訓練資料。請在建置和搜尋索引之前，展開設定區塊並執行它。

import random

from pymilvus import DataType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")
collection_name = "faiss_float_example"

if client.has_collection(collection_name):
    client.drop_collection(collection_name)

rng = random.Random(42)
vectors = [[rng.random() for _ in range(128)] for _ in range(3000)]

schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("category", DataType.VARCHAR, max_length=32)
schema.add_field("vector", DataType.FLOAT_VECTOR, dim=128)

client.create_collection(collection_name=collection_name, schema=schema)

rows = [
    {
        "id": i,
        "category": "reference" if i % 2 == 0 else "query",
        "vector": vector,
    }
    for i, vector in enumerate(vectors)
]

client.insert(collection_name=collection_name, data=rows)
client.flush(collection_name=collection_name)

建立索引

將 `index_type ` 設定為 `FAISS`，並使用 `faiss_index_name ` 選取原生 Faiss 工廠配方。

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="vector",
    index_name="faiss_ivf_flat",
    index_type="FAISS",
    metric_type="L2",
    params={"faiss_index_name": "IVF64,Flat"},
)

client.create_index(collection_name=collection_name, index_params=index_params)
client.load_collection(collection_name=collection_name)

工廠字串IVF64,Flat 會建立一個包含 64 個反轉清單的 IVF 索引，並在每個清單中儲存未壓縮的向量。

搜尋索引

請在search_params.params 內設定工廠專屬的搜尋參數。對於 IVF 工廠，nprobe 會控制 Faiss 搜尋的倒排列表數量。

search_params = {
    "params": {"nprobe": 8},
}

results = client.search(
    collection_name=collection_name,
    data=[vectors[0]],
    anns_field="vector",
    filter='category == "reference"',
    search_params=search_params,
    limit=5,
    output_fields=["category"],
)

for hits in results:
    for hit in hits:
        print(hit)

由於查詢使用了 `nprobe=8`，因此 Faiss 會從 64 個反轉清單中搜尋其中的 8 個。此篩選條件將結果限制為 `category ` 值為 `reference` 的實體。

建立並搜尋二進位索引

對於BINARY_VECTOR 欄位，請使用如BFlat 般的二進位建構字串，並搭配相容的二進位度量。請展開設定區塊並執行該區塊，然後再建立及搜尋索引。

import random

from pymilvus import DataType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")
collection_name = "faiss_binary_example"

if client.has_collection(collection_name):
    client.drop_collection(collection_name)

rng = random.Random(7)
vectors = [bytes(rng.getrandbits(8) for _ in range(16)) for _ in range(300)]

schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("binary_vector", DataType.BINARY_VECTOR, dim=128)

client.create_collection(collection_name=collection_name, schema=schema)
client.insert(
    collection_name=collection_name,
    data=[{"id": i, "binary_vector": vector} for i, vector in enumerate(vectors)],
)
client.flush(collection_name=collection_name)

建立索引

在此二進位向量範例中，請使用BFlat 作為生成字串，並使用HAMMING 作為度量。

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="binary_vector",
    index_name="faiss_binary_flat",
    index_type="FAISS",
    metric_type="HAMMING",
    params={"faiss_index_name": "BFlat"},
)

client.create_index(collection_name=collection_name, index_params=index_params)
client.load_collection(collection_name=collection_name)

搜尋索引

BFlat 沒有特定於家族的搜尋參數。在建構搜尋請求時，請傳入一個空的params 映射。

search_params = {"params": {}}

results = client.search(
    collection_name=collection_name,
    data=[vectors[0]],
    anns_field="binary_vector",
    search_params=search_params,
    limit=5,
)

for hits in results:
    for hit in hits:
        print(hit)

每個 128 維的二進位向量由 16 位元組表示。如需更多資訊，請參閱《二進位向量》。

設定建置與搜尋參數

FAISS 索引類型有一個必填的直通建置參數。

請在search_params.params 內設定工廠專屬的搜尋參數。下表列出常見範例，但並非詳盡無遺。

Milvus 僅會轉發適配器所識別的附加參數。未知建置金鑰以及具體工廠家族不支援的搜尋金鑰將被拒絕。Milvus 並未針對所有可能的工廠維護通用的參數架構。 請查閱所選工廠的 Faiss 文件，然後根據您計劃部署的 Milvus 確切版本和映像，驗證完整的建置與搜尋流程。

處理錯誤與不支援的操作

• 若工廠字串無效，或在 Milvus 建置中不可用，索引建置將失敗。在載入資料集之前，請檢查索引狀態與失敗原因。

• 若參數類型錯誤，搜尋將失敗。例如，nprobe="invalid" 會被拒絕，因為nprobe 必須為數值型別。

• 若某個參數不適用於已建置的工廠，適配器會以「不支援」為由拒絕該參數。

• 若某個工廠不支援 Milvus 選擇器，即使該工廠在獨立運作的 Faiss 中可進行搜尋，篩選搜尋仍可能失敗。

• 請勿在FAISS 索引中使用search_iterator() 。

接下來該做什麼

• 請參閱《索引說明》了解 Milvus 索引的組織方式。
• 比較專用的IVF_FLAT與HNSW索引類型。
• 在為工廠選擇指標之前，請先參閱《指標類型》。