Resaltador de textoCompatible with Milvus 2.6.8+

El Resaltador de Milvus anota los términos coincidentes en los campos de texto envolviéndolos con etiquetas personalizables. El resaltado ayuda a explicar por qué un documento coincide, mejora la legibilidad de los resultados y permite una representación enriquecida en las aplicaciones de búsqueda y RAG.

El resaltado se ejecuta como un paso de posprocesamiento en el conjunto final de resultados de búsqueda. No afecta a la recuperación de candidatos, la lógica de filtrado, la clasificación ni la puntuación.

El Resaltador ofrece tres dimensiones independientes de control:

• Qué términos se resaltan

  Puede elegir de dónde proceden los términos resaltados. Por ejemplo, resalte los términos de búsqueda utilizados en la búsqueda de texto completo de BM25, o los términos de consulta especificados en expresiones de filtrado basadas en texto (como las condiciones de TEXT_MATCH ).

• Cómo se muestran los términos resaltados

  Puede controlar cómo aparecen los términos coincidentes en la salida de resaltado configurando las etiquetas insertadas antes y después de cada coincidencia. Por ejemplo, utilice marcadores sencillos como {} o etiquetas HTML como <em></em> para una representación enriquecida.

• Cómo se devuelve el texto resaltado

  Puede controlar cómo se devuelven los resultados resaltados como fragmentos, incluyendo dónde empiezan los fragmentos, qué longitud tienen y cuántos fragmentos se devuelven.

En las secciones siguientes se describen estas opciones.

Resaltado de términos de búsqueda en la búsqueda de texto completo BM25

Cuando realice una búsqueda de texto completo en BM25, puede resaltar los términos de búsqueda en el resultado devuelto para ayudar a explicar por qué un documento coincide con la consulta. Para obtener más información sobre la búsqueda de texto completo en BM25, consulte Búsqueda de texto completo.

En este escenario, los términos resaltados proceden directamente de los términos de búsqueda utilizados en la búsqueda de texto completo BM25. El Resaltador utiliza estos términos para anotar el texto coincidente en el resultado final.

Supongamos que el siguiente contenido está almacenado en un campo de texto:

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

Configuración del Resaltador

Para resaltar los términos de búsqueda en la búsqueda de texto completo BM25, cree un LexicalHighlighter y active el resaltado de términos de búsqueda para la búsqueda de texto 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
)

En este ejemplo

• pre_tags y post_tags controlan cómo aparece el texto resaltado en la salida. En este caso, los términos coincidentes se incluyen en {} (por ejemplo, {term}). También puede proporcionar varias etiquetas en forma de lista (por ejemplo, ["<b>", "<i>"]). Cuando se resaltan varios términos, las etiquetas se aplican en orden y se giran según la secuencia de coincidencia.

• highlight_search_text=True indica a Milvus que utilice los términos de búsqueda en la búsqueda de texto completo BM25 como fuente de términos resaltados.

Una vez creado el objeto Resaltador, aplique su configuración a su petición de búsqueda de texto completo BM25:

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

Salida de resaltado

Cuando el resaltado está activado, Milvus devuelve el texto resaltado en un campo dedicado highlight. Por defecto, la salida resaltada se devuelve como un fragmento a partir del primer término encontrado.

En este ejemplo, el término buscado es "BM25", por lo que aparece resaltado en el resultado devuelto:

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

Para controlar la posición, la longitud y el número de fragmentos devueltos, consulte Devolver el texto resaltado como fragmentos.

Resaltado de términos de búsqueda en el filtrado

Además de resaltar términos de búsqueda, puede resaltar términos utilizados en expresiones de filtrado basadas en texto.

En este caso, los términos resaltados proceden de expresiones de filtrado basadas en texto. El filtrado determina qué documentos coinciden, mientras que el Resaltador anota los espacios de texto coincidentes.

Supongamos que el siguiente contenido se almacena en un campo de texto:

This document explains how text filtering works in Milvus.

Configuración del Resaltador

Para resaltar los términos de consulta utilizados en el filtrado, cree un LexicalHighlighter y defina un highlight_query que corresponda a la condición de filtrado:

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
    }]
)

En esta configuración

• pre_tags y post_tags controlan cómo aparece el texto resaltado en la salida. En este caso, los términos coincidentes están envueltos por {} (por ejemplo, {term}). También puede proporcionar varias etiquetas en forma de lista (por ejemplo, ["<b>", "<i>"]). Cuando se resaltan varios términos, las etiquetas se aplican en orden y se giran según la secuencia de coincidencia.

• highlight_query define qué términos de filtrado deben resaltarse.

Una vez creado el objeto Resaltador, aplique la misma expresión de filtrado y la configuración del resaltador a su petición de búsqueda:

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

Resaltado de resultados

Cuando se habilita el resaltado de términos de consulta para el filtrado, Milvus devuelve el texto resaltado en un campo dedicado de highlight. Por defecto, la salida resaltada se devuelve como un fragmento a partir del primer término coincidente.

En este ejemplo, el primer término coincidente es "text", por lo que el texto resaltado devuelto comienza a partir de esa posición:

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

Para controlar la posición, la longitud y el número de fragmentos devueltos, consulte Devolver el texto resaltado como fragmentos.

Salida de resaltado basada en fragmentos

Por defecto, Milvus devuelve el texto resaltado como fragmentos a partir del primer término coincidente. Los ajustes relacionados con los fragmentos le permiten controlar aún más cómo se devuelven los fragmentos, sin cambiar qué términos se resaltan.

Suponga que el siguiente contenido está almacenado en un campo de texto:

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

Configuración del resaltador

Para controlar la forma de los fragmentos resaltados, configure las opciones relacionadas con los fragmentos en 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
)

En esta configuración

• fragment_offset reserva el contexto inicial antes del primer término resaltado.

• fragment_size limita la cantidad de texto que se incluye en cada fragmento.

• num_of_fragments controla cuántos fragmentos se devuelven.

Una vez creado el objeto Resaltador, aplique la configuración del resaltador a su petición de búsqueda:

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

Resaltado de resultados

Con el resaltado basado en fragmentos activado, Milvus devuelve el texto resaltado como fragmentos en el campo highlight:

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

En este resultado:

• El fragmento no comienza exactamente en {BM25} porque fragment_offset está configurado.

• Sólo se devuelve un fragmento porque num_of_fragments es 1.

• La longitud del fragmento está limitada por fragment_size.

Ejemplos

Preparación

Antes de utilizar el resaltador, asegúrese de que su colección está correctamente configurada.

En el siguiente ejemplo se crea una colección compatible con la búsqueda de texto completo BM25 y las consultas TEXT_MATCH, y a continuación se insertan documentos de ejemplo.

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

Ejemplo 1: Resaltar términos de búsqueda en la búsqueda de texto completo BM25

Este ejemplo muestra cómo resaltar los términos de búsqueda en la búsqueda de texto completo BM25.

• La búsqueda de texto completo BM25 utiliza "test" como término de búsqueda

• El resaltador envuelve todas las apariciones de "test" con las etiquetas { y }

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']

Ejemplo 2: Resaltar términos de búsqueda en el filtrado

Este ejemplo muestra cómo resaltar los términos coincidentes con un filtro TEXT_MATCH.

• La búsqueda de texto completo BM25 utiliza "test" como término de consulta

• El parámetro queries añade "my doc" a la lista de términos destacados.

• El resaltador envuelve todos los términos coincidentes ("my", "test", "doc") con { y }

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']

Ejemplo 3: Devolución de elementos destacados como fragmentos

En este ejemplo, la consulta busca "Milvus" y devuelve fragmentos destacados con la siguiente configuración:

• fragment_offset mantiene hasta 20 caracteres antes del primer fragmento destacado como contexto inicial (por defecto es 0).

• fragment_size limita cada fragmento a unos 60 caracteres (por defecto, 100).

• num_of_fragments limita el número de fragmentos devueltos por valor de texto (por defecto es 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']

Ejemplo 4: Resaltado de consultas múltiples

Cuando se realizan búsquedas con varias consultas en la búsqueda de texto completo BM25, los resultados de cada consulta se resaltan de forma independiente. Los resultados de la primera consulta contienen los términos buscados, los de la segunda los términos buscados, y así sucesivamente. Cada consulta utiliza la misma configuración highlighter pero la aplica de forma independiente.

En el ejemplo siguiente

• La primera consulta resalta "test" en su conjunto de resultados.

• La segunda consulta resalta "Milvus" en su conjunto de resultados

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']

Ejemplo 5: Etiquetas HTML personalizadas

Puede utilizar cualquier etiqueta para el resaltado, como etiquetas HTML seguras para interfaces de usuario web. Esto resulta útil cuando se muestran los resultados de la búsqueda en un navegador.

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']