文字欄位Compatible with Milvus 3.0.x

在 AI 搜尋應用中，向量搜尋可協助您找出語義相似的實體，但應用程式通常也需要每個匹配結果背後的原始來源文字。大型語言模型（LLM）或代理程式可將該文字作為上下文，用於閱讀、引用、摘要，或將結果納入提示字串中。

Milvus 提供「TEXT 」標量欄位類型，可直接將長篇來源文字與實體一併儲存。典型值包括段落、長篇文件、文章正文、工單及日誌。與「VARCHAR 」不同，後者需要設定固定的「max_length 」，而「TEXT 」則無需在集合架構中設定最大位元組長度。

要定義TEXT 欄位，請將datatype 設定為DataType.TEXT 。

common.storage.useLoonFFI 預設值為 `false`，這表示 Storage V3 預設為停用狀態。在建立包含 `TEXT ` 欄位的集合之前，請將此參數設定為 `true`；否則，Milvus 將拒絕該集合架構。

schema.add_field(
    field_name="content",
    datatype=DataType.TEXT,
)

定義該欄位後，每個實體皆可在該欄位中包含字串值。您可像處理其他標量欄位一樣插入TEXT 值，並透過在output_fields 中列出該欄位，從查詢或搜尋結果中擷取這些值。

限制

• TEXT 欄位不能作為主欄位、分區鍵或叢集鍵。
• TEXT 無法用作ARRAY 欄位的元素類型，包括StructArray 中的標量子欄位。
• 在 Milvus 3.0.0 中，TEXT 欄位不支援預設值。
• 在 Milvus 3.0.0 中，外部集合不支援 `TEXT ` 欄位。
• 使用者無法在TEXT 欄位上建立標量索引。當enable_match=True 時，Milvus 會建立一個由系統管理的文字索引，用於文字比對。此內部索引並非使用者建立的標量索引。
• 一般標量篩選運算子無法直接套用至 `TEXT ` 欄位。 這些包括比較運算子（例如== 和!= ）、範圍運算子（例如> 、>= 、< 和<= ），以及IN 、LIKE 、正規表達式運算子（=~ 和!~ ）和IS NULL 或IS NOT NULL 。若要根據已分析的術語進行篩選，請使用enable_analyzer=True 和enable_match=True 定義欄位，並使用TEXT_MATCH 或TEXT_MATCH_FUZZY 。對於依相關性排序的全文檢索，請使用 BM25。
• 在 Milvus 3.0.0 中，若要使用以TEXT 欄位作為輸入的 BM25 或 MinHash 函式，必須在建立集合時即進行定義。即使現有集合為空，亦無法事後透過add_function_field 或AlterCollectionSchema 追加該函式，因為 Milvus 無法根據儲存的TEXT 值回填該函式的輸出結果。 若要將此類函數新增至現有集合，請使用「VARCHAR 」輸入欄位，或重新建立集合並將該函數納入其資料結構中。有關新增函數及其所產生向量欄位的詳細資訊，請參閱《變更集合資料結構》。
• 文字嵌入函數也必須在建立集合時一併定義。Milvus 3.0.0 不支援在執行階段新增這些函數。

請選擇 TEXT 或 VARCHAR

TEXT 和VARCHAR 皆用於儲存字串值，但它們支援不同的應用需求。請使用VARCHAR 來儲存用於識別、分類或篩選實體的簡短且範圍有限的元資料。請使用TEXT 來儲存較長的原始內容，以便為大型語言模型（LLM）或代理程式提供足夠的上下文，以進行閱讀、引用、摘要或建構提示詞。

適用情境	VARCHAR	TEXT
最適合	用於識別、分類或篩選實體的簡短元資料，例如title 、tag 、category 或external_id 。	用於大型語言模型（LLM）或代理工作流程的較長來源內容，例如content 、passage 、article_body 或log_message 。
長度設定	必須使用max_length ，該設定定義了該欄位可儲存的最大位元組數。最大值為65,535 位元組。若值可能超過此限制，請使用TEXT 。	無需指定max_length ，因此資料結構無需為文字值設定固定的位元組限制。
儲存行為	將每個值儲存於該欄位所設定的max_length 內。	對於較大的文字值，會使用自動儲存選取機制。詳細資訊請參閱《Milvus 如何儲存大型 TEXT 值》。
主要欄位支援	可用作主欄位。	無法用作主欄位。
篩選	適用於需要出現在篩選表達式中的短字串元資料，例如category == "news" 或tag in ["ai", "database"] 。	不支援一般的標量篩選運算子。請使用支援比對的文字運算子進行已分析術語篩選，或使用 BM25 進行依相關性排序的全文檢索。

有關VARCHAR 欄位的詳細資訊，請參閱VarChar 欄位。

Milvus 如何儲存大型 TEXT 值

展開以了解運作原理

當您插入實體時，您為TEXT 欄位提供的字串即為TEXT 值。Milvus 會將該值的大小與dataNode.text.inlineThreshold 進行比較（預設值為65,536 位元組），然後從兩種內部儲存路徑中選擇其一。

大容量文字儲存

• 內聯儲存：若TEXT 值小於dataNode.text.inlineThreshold ，Milvus 會將原始文字值直接儲存於TEXT 欄位的 data 中。
• LOB 儲存：若 `TEXT ` 的值大於或等於 `dataNode.text.inlineThreshold`，Milvus 會將該值視為大型物件，並將原始文字分別儲存於物件儲存空間（例如 MinIO）中。`TEXT ` 欄位資料則儲存指向該獨立儲存文字的內部參照。當在查詢或搜尋結果中請求 `TEXT ` 欄位時，Milvus 會使用該參照來擷取並回傳原始文字。

此儲存選項屬內部機制。無論 Milvus 使用哪種儲存路徑，您對TEXT 欄位的插入、查詢及搜尋操作方式皆相同。若要調整閾值或相關的儲存、壓縮及垃圾回收行為，請參閱與dataNode 相關的設定以及與 dataCoord 相關的設定。

若您的部署使用物件儲存，大型的 `TEXT ` 值可能會以 Milvus 管理的物件形式，出現在如lobs/... 等路徑下。這些物件屬於實作細節，不應手動移動、複製或刪除。 在刪除實體、釋放分區或壓縮資料後，物件儲存的使用量可能僅會在 Milvus 垃圾回收於安全時窗結束後，移除未被引用的巨型物件資料時才會減少。

TEXT 的常見應用之一是搭配 BM25 進行全文檢索。在此模式下，TEXT 欄位儲存原始來源內容，而 BM25 會分析文字並產生稀疏向量，以針對基於關鍵字的匹配結果進行排序。搜尋結果隨後可返回匹配的TEXT 值，作為大型語言模型 (LLM) 或代理程式工作流程的上下文。 以下範例展示如何將「TEXT 」欄位用作 BM25 的輸入欄位。如需瞭解全文搜尋的概念與查詢選項，請參閱《全文搜尋》。

步驟 1：建立包含 TEXT 欄位的集合

以下範例建立一個集合，其中包含用於來源內容的TEXT 欄位，以及用於 BM25 所產生稀疏向量的稀疏向量欄位。BM25 函式會將來自content 的分詞文字轉換為稀疏向量，並儲存於sparse 中。

若要進行 BM25 全文檢索，輸入的TEXT 欄位必須設定為enable_analyzer=True 。

from pymilvus import DataType, Function, FunctionType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")
COLLECTION_NAME = "text_bm25_collection"

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

schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field(field_name="id", datatype=DataType.INT64, is_primary=True)
schema.add_field(
    field_name="content",
    datatype=DataType.TEXT,
    enable_analyzer=True,
)
schema.add_field(field_name="sparse", datatype=DataType.SPARSE_FLOAT_VECTOR)

bm25_function = Function(
    name="content_bm25",
    input_field_names=["content"],
    output_field_names=["sparse"],
    function_type=FunctionType.BM25,
)
schema.add_function(bm25_function)

步驟 2：建立稀疏向量索引

針對由 BM25 函式所產生的稀疏向量欄位建立索引。度量類型必須設定為BM25 。

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="sparse",
    index_type="SPARSE_INVERTED_INDEX",
    metric_type="BM25",
    params={
        "inverted_index_algo": "DAAT_MAXSCORE",
        "bm25_k1": 1.2,
        "bm25_b": 0.75,
    },
)

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

步驟 3：插入 TEXT 資料

請直接將文字插入TEXT 欄位中。請勿為sparse 欄位提供值。Milvus 會透過將 BM25 函式套用至content ，在內部自動產生稀疏向量。

data = [
    {
        "id": 1,
        "content": "Milvus stores vector embeddings and scalar fields in collections. It supports vector search, full text search, and metadata filtering for retrieval applications.",
    },
    {
        "id": 2,
        "content": "Long documents are often split into passages before embedding. Store each passage in a TEXT field so search results can return the source text.",
    },
    {
        "id": 3,
        "content": "Operational logs and support tickets often contain long natural-language text. TEXT fields can store these values without a fixed max_length setting.",
    },
]

client.insert(collection_name=COLLECTION_NAME, data=data)
client.load_collection(collection_name=COLLECTION_NAME)

步驟 4：執行 BM25 全文檢索

將原始查詢文字用作搜尋資料，並針對稀疏向量欄位進行搜尋。Milvus 會將查詢文字轉換為稀疏向量，透過 BM25 對比結果進行排序，並將請求的TEXT 欄位結果回傳至output_fields 。

results = client.search(
    collection_name=COLLECTION_NAME,
    data=["how does Milvus store source text for retrieval"],
    anns_field="sparse",
    limit=2,
    output_fields=["content"],
)

步驟 5：讀取回傳的 TEXT 值

每個搜尋結果均包含 BM25 分數及原始的TEXT 值。

for hit in results[0]:
    print(f"id: {hit['id']}, score: {hit['distance']}")
    print(hit["entity"]["content"])

有關 BM25 函式、稀疏向量索引以及全文搜尋查詢語法的更多資訊，請參閱《全文搜尋》。