Evidenziatore di testoCompatible with Milvus 2.6.8+

L'evidenziatore di Milvus annota i termini corrispondenti nei campi di testo avvolgendoli con tag personalizzabili. L'evidenziazione aiuta a spiegare il motivo della corrispondenza di un documento, migliora la leggibilità dei risultati e supporta un rendering ricco nelle applicazioni di ricerca e RAG.

L'evidenziazione viene eseguita come fase di post-elaborazione del set di risultati della ricerca finale. Non influisce sul reperimento dei candidati, sulla logica di filtraggio, sulla classificazione o sul punteggio.

L'evidenziatore offre tre dimensioni di controllo indipendenti:

• Quali termini vengono evidenziati

  È possibile scegliere da dove provengono i termini evidenziati. Ad esempio, è possibile evidenziare i termini di ricerca utilizzati nella ricerca full text di BM25 o i termini della query specificati nelle espressioni di filtraggio basate sul testo (come le condizioni di TEXT_MATCH ).

• Come vengono resi i termini evidenziati

  È possibile controllare il modo in cui i termini corrispondenti appaiono nell'output di evidenziazione, configurando i tag inseriti prima e dopo ogni corrispondenza. Ad esempio, si possono usare marcatori semplici come {} o tag HTML come <em></em> per una resa più ricca.

• Come viene restituito il testo evidenziato

  È possibile controllare il modo in cui i risultati dell'evidenziazione vengono restituiti come frammenti, compreso l'inizio dei frammenti, la loro lunghezza e il numero di frammenti restituiti.

Le sezioni seguenti illustrano questi scenari.

Evidenziazione dei termini di ricerca nella ricerca full text BM25

Quando si esegue una ricerca full text in BM25, è possibile evidenziare i termini di ricerca nei risultati restituiti per spiegare perché un documento corrisponde alla query. Per ulteriori informazioni sulla ricerca full text in BM25, consultare la sezione Ricerca full text.

In questo scenario, i termini evidenziati provengono direttamente dai termini di ricerca utilizzati nella ricerca a testo pieno di BM25. L'evidenziatore utilizza questi termini per annotare il testo corrispondente nel risultato finale.

Si supponga che il seguente contenuto sia memorizzato in un campo di testo:

Milvus supports full text search. Use BM25 for keyword relevance. Filters can narrow results.

Configurazione dell'evidenziatore

Per evidenziare i termini di ricerca nella ricerca a testo completo BM25, creare un LexicalHighlighter e abilitare l'evidenziazione dei termini di ricerca per la ricerca a testo completo BM25:

from pymilvus import LexicalHighlighter

highlighter = LexicalHighlighter(
    pre_tags=["{"],              # Tag inserted before each highlighted term
    post_tags=["}"],             # Tag inserted after each highlighted term
    highlight_search_text=True   # Enable search term highlighting for BM25 full text search
)

In questo esempio:

• pre_tags e post_tags controllano il modo in cui il testo evidenziato appare nell'output. In questo caso, i termini corrispondenti sono avvolti da {} (ad esempio, {term}). È anche possibile fornire più tag come elenco (ad esempio, ["<b>", "<i>"]). Quando vengono evidenziati più termini, i tag vengono applicati in ordine e ruotati in base alla sequenza delle corrispondenze.

• highlight_search_text=True indica a Milvus di utilizzare i termini di ricerca nella ricerca full text di BM25 come fonte dei termini evidenziati.

Una volta creato l'oggetto Highlighter, applicare la sua configurazione alla richiesta di ricerca full text di BM25:

results = client.search(
    ...,
    data=["BM25"],      # Search term used in BM25 full text search
    highlighter=highlighter # Pass highlighter config here
)

Output dell'evidenziazione

Quando l'evidenziazione è abilitata, Milvus restituisce il testo evidenziato in un campo dedicato highlight. Per impostazione predefinita, l'output evidenziato viene restituito come frammento a partire dal primo termine trovato.

In questo esempio, il termine di ricerca è "BM25", quindi è evidenziato nel risultato restituito:

{
    ...,
    "highlight": {
        "text": [
            "{BM25} for keyword relevance. Filters can narrow results."
        ]
    }
}

Per controllare la posizione, la lunghezza e il numero di frammenti restituiti, vedere Restituzione del testo evidenziato come frammenti.

Evidenziazione dei termini di ricerca nel filtraggio

Oltre a evidenziare i termini di ricerca, è possibile evidenziare i termini utilizzati nelle espressioni di filtraggio basate sul testo.

In questo scenario, i termini evidenziati provengono da espressioni di filtraggio basate sul testo. Il filtro determina quali documenti corrispondono, mentre l'evidenziatore annota gli intervalli di testo corrispondenti.

Si supponga che il seguente contenuto sia memorizzato in un campo di testo:

This document explains how text filtering works in Milvus.

Configurazione dell'evidenziatore

Per evidenziare i termini della query usati nel filtraggio, creare un LexicalHighlighter e definire un highlight_query che corrisponda alla condizione di filtraggio:

from pymilvus import LexicalHighlighter

highlighter = LexicalHighlighter(
    pre_tags=["{"],              # Tag inserted before each highlighted term
    post_tags=["}"],             # Tag inserted after each highlighted term
    highlight_query=[{
        "type": "TextMatch",     # Text filtering type
        "field": "text",         # Target text field
        "text": "text filtering" # Terms to highlight
    }]
)

In questa configurazione:

• pre_tags e post_tags controllano il modo in cui il testo evidenziato appare nell'output. In questo caso, i termini corrispondenti sono avvolti da {} (ad esempio, {term}). È anche possibile fornire più tag come elenco (ad esempio, ["<b>", "<i>"]). Quando vengono evidenziati più termini, i tag vengono applicati in ordine e ruotati in base alla sequenza delle corrispondenze.

• highlight_query definisce quali termini di filtraggio devono essere evidenziati.

Una volta creato l'oggetto Highlighter, applicare la stessa espressione di filtraggio e la configurazione dell'evidenziatore alla richiesta di ricerca:

results = client.search(
    ...,
    filter='TEXT_MATCH(text, "text filtering")',
    highlighter=highlighter # Pass highlighter config here
)

Evidenziazione dell'output

Quando l'evidenziazione dei termini della query è abilitata per il filtraggio, Milvus restituisce il testo evidenziato in un campo dedicato highlight. Per impostazione predefinita, l'output evidenziato viene restituito come frammento a partire dal primo termine corrispondente.

In questo esempio, il primo termine corrispondente è "text", quindi il testo evidenziato restituito inizia da quella posizione:

{
    ...,
    "highlight": {
        "text": [
            "{text} {filtering} works in Milvus."
        ]
    }
}

Per controllare la posizione, la lunghezza e il numero di frammenti restituiti, vedere Restituzione del testo evidenziato come frammenti.

Output dell'evidenziazione basato sui frammenti

Per impostazione predefinita, Milvus restituisce il testo evidenziato come frammenti a partire dal primo termine corrispondente. Le impostazioni relative ai frammenti consentono di controllare ulteriormente il modo in cui vengono restituiti i frammenti, senza modificare i termini evidenziati.

Si supponga che il seguente contenuto sia memorizzato in un campo di testo:

Milvus supports full text search. Use BM25 for keyword relevance. Filters can narrow results.

Configurazione dell'evidenziatore

Per controllare la forma dei frammenti evidenziati, configurare le opzioni relative ai frammenti in LexicalHighlighter:

from pymilvus import LexicalHighlighter

highlighter = LexicalHighlighter(
    pre_tags=["{"],
    post_tags=["}"],
    highlight_search_text=True,
    fragment_offset=5,     # Number of characters to reserve before the first matched term
    fragment_size=60,      # Max. length of each fragment to return
    num_of_fragments=1     # Max. number of fragments to return
)

In questa configurazione:

• fragment_offset riserva il contesto iniziale prima del primo termine evidenziato.

• fragment_size limita la quantità di testo inclusa in ogni frammento.

• num_of_fragments controlla il numero di frammenti restituiti.

Una volta creato l'oggetto Highlighter, applicare la configurazione dell'evidenziatore alla richiesta di ricerca:

results = client.search(
    ...,
    data=["BM25"],
    highlighter=highlighter # Pass highlighter config here
)

Evidenziazione dell'output

Con l'evidenziazione basata sui frammenti abilitata, Milvus restituisce il testo evidenziato come frammenti nel campo highlight:

{
    ...,
    "highlight": {
        "text": [
            "Use {BM25} for keyword relevance. Filters can narrow results."
        ]
    }
}

In questo output:

• Il frammento non inizia esattamente da {BM25} perché fragment_offset è impostato.

• Viene restituito solo un frammento perché num_of_fragments è 1.

• La lunghezza del frammento è limitata da fragment_size.

Esempi

Preparazione

Prima di usare l'evidenziatore, assicurarsi che la collezione sia configurata correttamente.

L'esempio seguente crea una raccolta che supporta la ricerca full text BM25 e le query TEXT_MATCH, quindi inserisce i documenti di esempio.

from pymilvus import (
    MilvusClient,
    DataType,
    Function,
    FunctionType,
    LexicalHighlighter,
)

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

# Clean up existing collection
if client.has_collection(COLLECTION_NAME):
    client.drop_collection(COLLECTION_NAME)

# Define schema
schema = client.create_schema(enable_dynamic_field=False)
schema.add_field(field_name="id", datatype=DataType.INT64, is_primary=True, auto_id=True)
schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=2000,
    enable_analyzer=True,  # Required for BM25
    enable_match=True,     # Required for TEXT_MATCH
)
schema.add_field(field_name="sparse_vector", datatype=DataType.SPARSE_FLOAT_VECTOR)

# Add BM25 function
schema.add_function(Function(
    name="text_bm25",
    function_type=FunctionType.BM25,
    input_field_names=["text"],
    output_field_names=["sparse_vector"],
))

# Create index
index_params = client.prepare_index_params()
index_params.add_index(
    field_name="sparse_vector",
    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)

# Insert sample documents
docs = [
    "my first test doc",
    "my second test doc",
    "my first test doc. Milvus is an open-source vector database built for GenAI applications.",
    "my second test doc. Milvus is an open-source vector database that suits AI applications "
    "of every size from running a demo chatbot to building web-scale search.",
]
client.insert(collection_name=COLLECTION_NAME, data=[{"text": t} for t in docs])
print(f"✓ Collection created with {len(docs)} documents\n")

# Helper for search params
SEARCH_PARAMS = {"metric_type": "BM25", "params": {"drop_ratio_search": 0.0}}

# Expected output:
# ✓ Collection created with 4 documents

Esempio 1: Evidenziare i termini di ricerca nella ricerca full text BM25

Questo esempio mostra come evidenziare i termini di ricerca nella ricerca full text BM25.

• La ricerca BM25 full text utilizza "test" come termine di ricerca.

• L'evidenziatore avvolge tutte le occorrenze di "test" con i tag { e }

highlighter = LexicalHighlighter(
    pre_tags=["{"],
    post_tags=["}"],
    highlight_search_text=True,  # Highlight BM25 query terms
)

results = client.search(
    collection_name=COLLECTION_NAME,
    data=["test"],
    anns_field="sparse_vector",
    limit=10,
    search_params=SEARCH_PARAMS,
    output_fields=["text"],
    highlighter=highlighter,
)

for hit in results[0]:
    print(f"  {hit.get('highlight', {}).get('text', [])}")
print()

['{test} doc']
['{test} doc']
['{test} doc. Milvus is an open-source vector database built for GenAI applications.']
['{test} doc. Milvus is an open-source vector database that suits AI applications of every size from run']

Esempio 2: Evidenziare i termini della query nel filtro

Questo esempio mostra come evidenziare i termini corrispondenti a un filtro TEXT_MATCH.

• La ricerca full text di BM25 utilizza "test" come termine di interrogazione.

• Il parametro queries aggiunge "my doc" all'elenco di evidenziazione.

• L'evidenziatore avvolge tutti i termini corrispondenti ("my", "test", "doc") con { e }

highlighter = LexicalHighlighter(
    pre_tags=["{"],
    post_tags=["}"],
    highlight_search_text=True,   # Also highlight BM25 term
    highlight_query=[                     # Additional TEXT_MATCH terms to highlight
        {"type": "TextMatch", "field": "text", "text": "my doc"},
    ],
)

results = client.search(
    collection_name=COLLECTION_NAME,
    data=["test"],
    anns_field="sparse_vector",
    limit=10,
    search_params=SEARCH_PARAMS,
    output_fields=["text"],
    highlighter=highlighter,
)

for hit in results[0]:
    print(f"  {hit.get('highlight', {}).get('text', [])}")
print()

['{my} first {test} {doc}']
['{my} second {test} {doc}']
['{my} first {test} {doc}. Milvus is an open-source vector database built for GenAI applications.']
['{my} second {test} {doc}. Milvus is an open-source vector database that suits AI applications of every siz']

Esempio 3: Restituzione di evidenziazioni come frammenti

In questo esempio, la query cerca "Milvus" e restituisce frammenti di evidenziazione con le seguenti impostazioni:

• fragment_offset mantiene fino a 20 caratteri prima del primo intervallo evidenziato come contesto iniziale (l'impostazione predefinita è 0).

• fragment_size limita ogni frammento a circa 60 caratteri (l'impostazione predefinita è 100).

• num_of_fragments limita il numero di frammenti restituiti per ogni valore di testo (l'impostazione predefinita è 5).

highlighter = LexicalHighlighter(
    pre_tags=["{"],
    post_tags=["}"],
    highlight_search_text=True,
    fragment_offset=20,  # Keep 20 chars before match
    fragment_size=60,    # Max ~60 chars per fragment
)

results = client.search(
    collection_name=COLLECTION_NAME,
    data=["Milvus"],
    anns_field="sparse_vector",
    limit=10,
    search_params=SEARCH_PARAMS,
    output_fields=["text"],
    highlighter=highlighter,
)

for i, hit in enumerate(results[0]):
    frags = hit.get('highlight', {}).get('text', [])
    print(f"  Doc {i+1}: {frags}")
print()

Doc 1: ['my first test doc. {Milvus} is an open-source vector database ']
Doc 2: ['my second test doc. {Milvus} is an open-source vector database']

Esempio 4: Evidenziazione di più query

Quando si effettuano ricerche con più query nella ricerca full text di BM25, i risultati di ciascuna query vengono evidenziati in modo indipendente. I risultati della prima query contengono evidenziazioni per il suo termine di ricerca, quelli della seconda query contengono evidenziazioni per il suo termine di ricerca e così via. Ogni query utilizza la stessa configurazione di highlighter, ma la applica in modo indipendente.

Nell'esempio seguente:

• La prima query evidenzia "test" nel suo set di risultati.

• La seconda query evidenzia "Milvus" nel suo insieme di risultati.

highlighter = LexicalHighlighter(
    pre_tags=["{"],
    post_tags=["}"],
    highlight_search_text=True,
)

results = client.search(
    collection_name=COLLECTION_NAME,
    data=["test", "Milvus"],  # Two queries
    anns_field="sparse_vector",
    limit=2,
    search_params=SEARCH_PARAMS,
    output_fields=["text"],
    highlighter=highlighter,
)

for nq_idx, hits in enumerate(results):
    query_term = ["test", "Milvus"][nq_idx]
    print(f"  Query '{query_term}':")
    for hit in hits:
        print(f"    {hit.get('highlight', {}).get('text', [])}")
print()

Query 'test':
  ['{test} doc']
  ['{test} doc']
Query 'Milvus':
  ['{Milvus} is an open-source vector database built for GenAI applications.']
  ['{Milvus} is an open-source vector database that suits AI applications of every size from running a dem']

Esempio 5: Tag HTML personalizzati

È possibile utilizzare qualsiasi tag per l'evidenziazione, ad esempio i tag HTML-safe per le interfacce web. Questo è utile quando si rendono i risultati della ricerca in un browser.

highlighter = LexicalHighlighter(
    pre_tags=["<mark>"],
    post_tags=["</mark>"],
    highlight_search_text=True,
)

results = client.search(
    collection_name=COLLECTION_NAME,
    data=["test"],
    anns_field="sparse_vector",
    limit=2,
    search_params=SEARCH_PARAMS,
    output_fields=["text"],
    highlighter=highlighter,
)

for hit in results[0]:
    print(f"  {hit.get('highlight', {}).get('text', [])}")
print()

['<mark>test</mark> doc']
['<mark>test</mark> doc']