Consulta basada en vectores - OpenSearch - Centro de documentación de Alibaba Cloud

Envíe un vector a OpenSearch Vector Search Edition y recupere los documentos más similares de su índice. Si no cuenta con un modelo de vectores, utilice las funciones image vectorization o text vectorization para generar vectores con modelos integrados y, a continuación, ejecute prediction-based queries.

Endpoint

POST /vector-service/query

Protocolo: HTTP Formato: JSON

Nota: La ruta del endpoint omite la URL base de su aplicación de OpenSearch y cualquier encabezado de solicitud. Consulte Firma de la solicitud para obtener detalles sobre la autenticación.

Firma de la solicitud

El encabezado authorization contiene una cadena username:password codificada en Base64. Encuentre sus credenciales en la sección API Endpoint de la página Instance Details.

import com.aliyun.darabonba.encode.Encoder;
import com.aliyun.darabonbastring.Client;

public class GenerateAuthorization {

    public static void main(String[] args) throws Exception {
        String accessUserName = "username";
        String accessPassWord = "password";
        String realmStr = "" + accessUserName + ":" + accessPassWord + "";
        String authorization = Encoder.base64EncodeToString(Client.toBytes(realmStr, "UTF-8"));
        System.out.println(authorization);
    }
}

El valor codificado tiene el siguiente aspecto:

cm9vdDp******mdhbA==

Establezca el encabezado en cada solicitud:

authorization: Basic cm9vdDp******mdhbA==

Parámetros de la solicitud

De forma predeterminada, la respuesta solo incluye id y score, sin valores de campos ni datos de vectores. Configure outputFields y includeVector para incluir datos adicionales.

Parámetro	Tipo	Obligatorio	Valor predeterminado	Descripción
`tableName`	STRING	Sí	—	Nombre de la tabla que se va a consultar.
`vector`	LIST[FLOAT]	Sí	—	Vector de consulta. Para varios vectores, concaténelos en una sola matriz y establezca `vectorCount`.
`vectorCount`	INT	No	`1`	Número de vectores en la matriz `vector`.
`namespace`	STRING	No	`""`	Namespace de los datos vectoriales. Si se configuró un namespace en el índice vectorial, este campo es obligatorio.
`topK`	INT	No	`100`	Número máximo de resultados que se devolverán.
`includeVector`	BOOLEAN	No	`false`	Especifica si se debe devolver el vector sin procesar en cada resultado. Establézcalo en `true` solo cuando necesite los valores del vector; omitirlo reduce el tamaño de la respuesta y la latencia.
`outputFields`	LIST[STRING]	No	`[]`	Nombres de los campos que se incluirán en cada resultado. Omítalo para devolver solo `id` y `score`.
`order`	STRING	No	`ASC`	Dirección de ordenamiento para la clasificación principal. Valores válidos: `ASC`, `DESC`.
`searchParams`	STRING	No	`""`	Configuración del buscador codificada en JSON. Admite los parámetros QcSearcher y HnswSearcher.
`filter`	STRING	No	`""`	Filter expression para limitar los resultados antes de la clasificación.
`scoreThreshold`	FLOAT	No	—	Umbral de puntuación para filtrar resultados. Para la distancia euclidiana al cuadrado, solo se devuelven los documentos con una puntuación inferior al umbral. Para el producto interno, solo se devuelven los documentos con una puntuación superior al umbral.
`sort`	STRING	No	`""`	Expresión de ordenamiento para combinar la similitud vectorial con otros campos. Utilice `_vs_vector_score` para incluir la puntuación del vector; por ejemplo: `-create_gmt;+_vs_vector_score`.
`sorts`	LIST[Sort]	No	`[]`	Ordenamiento multidimensional. Cuando se establece, el valor `score` en los resultados refleja las dimensiones de ordenamiento configuradas.

Objeto Sort

Parámetro	Tipo	Obligatorio	Valor predeterminado	Descripción
`order`	STRING	No	`""`	Dirección de ordenamiento. Valores válidos: `ASC` (ascendente), `DESC` (descendente).
`expression`	STRING	No	`""`	Expresión utilizada para el ordenamiento.

Ejemplos

Consulta de un solo vector

Solicitud:

{
    "tableName": "gist",
    "vector": [0.1, 0.2, 0.3],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Respuesta:

{
    "result": [
        {"id": 1, "score": 1.0508723258972169, "vector": [0.1, 0.2, 0.3]},
        {"id": 2, "score": 1.0329746007919312, "vector": [0.2, 0.2, 0.3]},
        {"id": 3, "score": 0.980593204498291,  "vector": [0.3, 0.2, 0.3]}
    ],
    "totalCount": 3,
    "totalTime": 2.943
}

Consulta basada en namespace

Los namespaces dividen un índice vectorial en subconjuntos aislados. Si se configuró un namespace en el índice, debe incluirlo en cada consulta.

{
    "tableName": "gist",
    "namespace": "space_b",
    "vector": [0.1, 0.2],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Consulta en varios namespaces

Utilice la matriz queries para buscar en varios namespaces dentro de una sola solicitud. OpenSearch combina y clasifica los resultados, y luego devuelve los K principales.

{
    "tableName": "gist",
    "queries": [
        {"vector": [0.1, 0.2, 0.3], "namespace": "space_a"},
        {"vector": [0.4, 0.5, 0.6], "namespace": "space_b"}
    ],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Consulta con condiciones de filtro

Utilice una expresión de filtro para restringir los candidatos antes de la clasificación. Combínela con outputFields para controlar qué campos se devuelven.

{
    "tableName": "gist",
    "vector": [0.1, 0.2],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "filter": "a > 10",
    "includeVector": true,
    "outputFields": ["a", "b"]
}

Consulta de múltiples vectores

Concatene todos los vectores en la matriz vector y establezca vectorCount con la cantidad de vectores. OpenSearch combina y clasifica los resultados de todos los vectores, y luego devuelve los K principales. El siguiente ejemplo consulta dos vectores bidimensionales:

{
    "tableName": "gist",
    "vector": [0.1, 0.2, 0.3, 0.4],
    "vectorCount": 2,
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true,
    "outputFields": ["a", "b"]
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`result`	LIST[Item]	Lista clasificada de documentos coincidentes.
`totalCount`	INT	Número de resultados devueltos.
`totalTime`	FLOAT	Latencia de la consulta en milisegundos.
`errorCode`	INT	Código de error. Presente solo cuando la solicitud falla.
`errorMsg`	STRING	Mensaje de error. Presente solo cuando la solicitud falla.

Item

Parámetro	Tipo	Descripción
`id`	FieldType	Clave principal del documento.
`score`	FLOAT	Puntuación de similitud. La dirección depende de la métrica de distancia: para la distancia euclidiana al cuadrado, una puntuación más baja indica mayor similitud; para el producto interno, una puntuación más alta indica mayor similitud.
`fields`	MAP	Los campos y sus valores correspondientes.
`vector`	LIST[FLOAT]	El valor del vector.
`namespace`	STRING	Namespace del documento. Se devuelve solo cuando hay un namespace configurado.