La recuperación de agentes (antes Vector Search 2.0) proporciona VertexRanker para la reclasificación semántica, que cuenta con la tecnología de la API de clasificación.
Después de que la recuperación de agentes recupera y fusiona los resultados candidatos
(con la fusión por clasificación recíproca [RRF]), VertexRanker vuelve a calificar los candidatos
fusionados con tu consulta en lenguaje natural usando un modelo semántico dedicado.
Esto mejora la relevancia de los resultados de top-k, en especial para las consultas en las que
la búsqueda por sí sola no tiene matices. La reclasificación se realiza en el servidor con llamadas a
BatchSearchDataObjects. No se necesitan conexiones adicionales del lado del cliente ni viajes de ida y vuelta adicionales.
VertexRanker
VertexRanker se configura como el reclasificador para el campo combine.ranker del
objeto BatchSearchDataObjectsRequest. Debes configurar un clasificador principal
(solo se admite RRF). El reranker se ejecuta después del paso de fusión de RRF y
reemplaza el resultado por la lista con una nueva puntuación semántica.
En la siguiente tabla, se enumeran los campos de configuración del clasificador.
| Campo | Obligatorio | Descripción |
|---|---|---|
combine.ranker.rrf.weights |
Sí | Son los pesos para la fusión de RRF de los resultados de la búsqueda subyacentes. |
combine.ranker.vertex_ranker.model |
Sí | Es el nombre del modelo de clasificación. Valores admitidos: semantic-ranker-fast@latest, semantic-ranker-default@latest, semantic-ranker-fast-004, semantic-ranker-default-004. Consulta los modelos de la API de Ranking para obtener detalles sobre cada uno. |
combine.ranker.vertex_ranker.top_n |
Sí | Es la cantidad máxima de candidatos de la lista fusionada que se enviarán al clasificador. Los valores válidos van desde 1 hasta 1000. |
combine.ranker.vertex_ranker.text_record_spec.query |
Sí | Es la consulta en lenguaje natural que usa el clasificador para puntuar los registros. |
combine.ranker.vertex_ranker.text_record_spec.title_template |
Sí | Es la cadena de plantilla, por ejemplo, {title}, que especifica cómo extraer (construir) el título de cada registro. Usa rutas de puntos para especificar campos de datos. |
combine.ranker.vertex_ranker.text_record_spec.content_template |
Sí | Es la cadena de plantilla, por ejemplo, {body.text}, que especifica cómo extraer (construir) el contenido principal de cada registro. Usa rutas de puntos para especificar campos de datos. |
combine.top_k |
Opcional | Es la cantidad final de resultados que se mostrarán después de volver a clasificarlos. Este valor debe ser menor o igual que vertex_ranker.top_n y menor o igual que 1,000. |
En el siguiente ejemplo, se muestra el cuerpo de una solicitud.
{
"searches": [
{ "semantic_search": { "search_text": "running shoes", "search_field": "embedding", "task_type": "RETRIEVAL_QUERY", "top_k": 50 } },
{ "text_search": { "search_text": "running shoes", "data_field_names": ["title"], "top_k": 50 } }
],
"combine": {
"top_k": 10,
"ranker": {
"rrf": { "weights": [1.0, 1.0] },
"vertex_ranker": {
"model": "semantic-ranker-fast@latest",
"top_n": 50,
"text_record_spec": {
"query": "running shoes",
"title_template": "{title}",
"content_template": "{body.text}"
}
}
}
}
}
Las plantillas usan rutas de acceso con puntos a los campos de datos del objeto de datos, por ejemplo, {title}
o {nested.field}. Estos campos deben existir en el esquema de la colección;
de lo contrario, la solicitud se rechazará durante la validación. Si a un objeto de datos le falta el campo proporcionado, el servidor vuelve a recuperar de forma transparente el registro completo del almacenamiento para que la plantilla se pueda completar.
Cuota y precios
VertexRanker en Agent Retrieval usa una asignación de nivel gratuito con facturación por excedente basada en el uso. Cada proyecto recibe una asignación gratuita de uso de clasificación por período de 30 días. El uso dentro de este límite no genera costos. Los precios estándar de la API de clasificación se aplican al proyecto del consumidor por cualquier uso que supere este límite.
En la siguiente tabla, se enumeran los valores de cuota.
| Elemento | Valor |
|---|---|
| Asignación del nivel gratuito | 80,000 unidades de clasificación por proyecto de consumidor por período de 30 días |
| Excedente | Se factura según los precios estándar de la API de clasificación en el proyecto del consumidor. |
| Cantidad máxima de registros por llamada de reclasificación | 1000 (top_n debe estar en el rango [1, 1000] y top_k <= top_n). |
Si alcanzas el límite del nivel gratuito, tus solicitudes no fallarán. Después de que se consuma la asignación de 80,000 unidades de clasificación, el uso posterior de VertexRanker seguirá funcionando correctamente y se facturará como excedente. La asignación se restablece 30 días después de la primera vez que la usaste.
Las unidades de clasificación se calculan a partir de la cantidad de registros enviados al clasificador y el tamaño de sus plantillas de título y contenido, con la misma contabilidad que la API de clasificación independiente. Consulta los precios de la API de Ranking para obtener todos los detalles.
Antes de poder usar VertexRanker, se debe habilitar Discovery Engine en el proyecto del consumidor. Para obtener más información, consulta Condiciones de falla.
Manejo de fallas y advertencias
VertexRanker es un reclasificador que hace su mejor esfuerzo. Si la llamada de clasificación falla, la RPC BatchSearchDataObjects se ejecuta correctamente y devuelve los resultados fusionados con RRF truncados a top_k. La falla se informa en el campo search_response_metadata.warnings de la respuesta. Se conserva el código de estado completo
de la API de clasificación. El código de advertencia para los estados inesperados es
UNAVAILABLE con el mensaje de advertencia:
"Reranking is temporarily unavailable. Returning fused (RRF) results without
semantic reranking."
Condiciones de falla
Toda la RPC BatchSearchDataObjects falla con FAILED_PRECONDITION
(sin resguardo a RRF) en los siguientes casos.
- La API de Discovery Engine no está habilitada: La API de clasificación devuelve
FAILED_PRECONDITIONcon el mensajeDiscovery Engine API is not enabled for the consumer project /<N/>. Please enable the API and try again."Solución: Habilita la API de Discovery Engine en el proyecto del consumidor.
El cliente debe habilitar Discovery Engine para el proyecto de consumidor para que se produzca la reclasificación.
En la siguiente tabla, se enumeran los códigos de advertencia, las causas habituales que generan las advertencias y el mensaje que explica la advertencia.
| Código de advertencia | Causa habitual | Mensaje de advertencia |
|---|---|---|
RESOURCE_EXHAUSTED |
Se superó una cuota de la API de Ranking en el proyecto del consumidor. Nota: Exceder el límite de 80,000 unidades de clasificación no genera esta advertencia, sino que se factura el excedente. | <Quota exceeded message>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N> |
DEADLINE_EXCEEDED |
Ranker.Rank no se completó dentro del plazo de la solicitud. |
<deadline-exceeded message from Ranker.Rank>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N> |
UNAVAILABLE |
Ranker.Rank devolvió UNAVAILABLE o un código no conservado (por ejemplo, INTERNAL) que se contrae a UNAVAILABLE. |
Si el código subyacente es UNAVAILABLE: "RankService.Rank call failed for consumer project... De lo contrario: "Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking." |
FAILED_PRECONDITION |
Cualquier FAILED_PRECONDITION que devuelva la API de clasificación. |
RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N> |
CANCELLED |
El emisor canceló la RPC BatchSearchDataObjects antes de que se completara la reclasificación. |
<cancellation message from the cancelled RankService.Rank RPC>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N> |