Getting Started - DashVector: Central de Documentação do Alibaba Cloud

O DashText é um codificador de vetores esparsos recomendado para o DashVector. A busca semântica captura o significado, mas pode não identificar correspondências exatas de palavras-chave — termos específicos de domínio, nomes de produtos ou códigos de erro frequentemente passam despercebidos. O DashText preenche essa lacuna ao converter texto em vetores esparsos usando o algoritmo BM25. Combine esses vetores esparsos com vetores densos no DashVector para executar uma busca semântica com reconhecimento de palavras-chave — uma recuperação simultaneamente relevante do ponto de vista semântico e precisa quanto às palavras-chave.

Exemplo principal

O trecho Python a seguir mostra o fluxo completo mínimo: crie uma coleção, codifique um documento, insira-o e execute uma consulta híbrida.

import dashvector
from dashtext import SparseVectorEncoder
from dashvector import Doc

# Connect to DashVector
client = dashvector.Client(
    api_key='YOUR_API_KEY',
    endpoint='YOUR_CLUSTER_ENDPOINT'
)

# Create a collection with dot product metric (required for sparse vectors)
client.create('hybrid_collection', dimension=4, metric='dotproduct')
collection = client.get('hybrid_collection')

# Build a sparse vector encoder and encode a document
encoder = SparseVectorEncoder.default()
doc_sparse = encoder.encode_documents("Your document text here.")

# Insert the document with both dense and sparse vectors
collection.insert(Doc(
    id='doc1',
    vector=[0.1, 0.2, 0.3, 0.4],
    sparse_vector=doc_sparse
))

# Search with both dense and sparse vectors
query_sparse = encoder.encode_queries("Your search query here.")
results = collection.query(
    vector=[0.1, 0.1, 0.1, 0.1],
    sparse_vector=query_sparse
)

As seções abaixo detalham cada etapa, com exemplos em Python e Java.

Pré-requisitos

Antes de começar, verifique se você tem:

Um cluster do DashVector com uma chave de API e um endpoint disponíveis. Para mais informações, consulte Introdução a vetores
SDK do Python ou Java instalado (pacotes dashvector e dashtext para Python)

Nota

Todos os exemplos neste guia usam vetores densos de 4 dimensões para simplificar. Em produção, defina a dimensão para corresponder à saída do seu modelo de embedding.

Etapa 1: Crie uma coleção com suporte a vetores esparsos

Vetores esparsos exigem a métrica de distância por produto escalar. Crie uma coleção com metric='dotproduct' para ativar o suporte a vetores esparsos.

Python

import dashvector

client = dashvector.Client(
    api_key='YOUR_API_KEY',
    endpoint='YOUR_CLUSTER_ENDPOINT'
)
assert client

# Create a collection with dot product metric (required for sparse vectors)
ret = client.create('hybrid_collection', dimension=4, metric='dotproduct')
assert ret

collection = client.get('hybrid_collection')
assert collection

Java

import com.aliyun.dashvector.DashVectorClient;
import com.aliyun.dashvector.DashVectorCollection;
import com.aliyun.dashvector.models.requests.CreateCollectionRequest;
import com.aliyun.dashvector.models.responses.Response;
import com.aliyun.dashvector.proto.CollectionInfo;

DashVectorClient client =
  new DashVectorClient("YOUR_API_KEY", "YOUR_CLUSTER_ENDPOINT");

CreateCollectionRequest request = CreateCollectionRequest.builder()
            .name("hybrid_collection")
            .dimension(4)
            .metric(CollectionInfo.Metric.dotproduct)
            .dataType(CollectionInfo.DataType.FLOAT)
            .build();

Response<Void> response = client.create(request);
System.out.println(response);

DashVectorCollection collection = client.get("hybrid_collection");

Importante

Apenas coleções que usam a métrica de produto escalar (metric='dotproduct') suportam vetores esparsos.

Substitua YOUR_API_KEY pela sua chave de API e YOUR_CLUSTER_ENDPOINT pelo endpoint do seu cluster para que o código seja executado corretamente.

Etapa 2: Construa um codificador de vetores esparsos

O DashText oferece duas abordagens para criar um SparseVectorEncoder: um codificador integrado para texto de uso geral e um codificador personalizado treinado em seu próprio corpus para maior precisão com termos específicos de domínio.

Use o codificador integrado

O codificador integrado é pré-treinado no corpus da Wikipédia em chinês e utiliza o Jieba para segmentação de texto em chinês. Nenhum treinamento adicional é necessário.

Python

from dashtext import SparseVectorEncoder

encoder = SparseVectorEncoder.default()

Java

import com.aliyun.dashtext.encoder.SparseVectorEncoder;

SparseVectorEncoder encoder = SparseVectorEncoder.getDefaultInstance();

Treine um codificador personalizado com seu próprio corpus

Para dados com muitos termos específicos de domínio, treine um codificador com todo o seu corpus para melhorar a precisão. Para mais informações, consulte Uso avançado.

Python

from dashtext import SparseVectorEncoder

encoder = SparseVectorEncoder()

# Your own corpus
corpus = [
    "DashVector is a vector retrieval service built on Proxima, Alibaba Cloud's in-house high-performance vector engine, offering a cloud-native, fully managed, and horizontally scalable vector retrieval service",
    "DashVector exposes its powerful vector management and query capabilities through simple, easy-to-use SDK/API interfaces, making it easy for upper-layer AI applications to integrate quickly",
    "This delivers the efficient vector retrieval capabilities required by a wide range of scenarios, including large model ecosystems, multimodal AI search, and molecular structure analysis",
    "A simple, flexible, out-of-the-box SDK that achieves vector management with minimal code",
    "In-house vector similarity algorithms deliver fast, efficient, and stable service",
    "Schema-free design that supports combined filtering queries under any conditions via Schema"
]

# Train the encoder on the full corpus
encoder.train(corpus)

Java

import com.aliyun.dashtext.encoder.SparseVectorEncoder;
import java.util.*;

SparseVectorEncoder encoder = new SparseVectorEncoder();

// Your own corpus
List<String> corpus = Arrays.asList(
  "DashVector is a vector retrieval service built on Proxima, Alibaba Cloud's in-house high-performance vector engine, offering a cloud-native, fully managed, and horizontally scalable vector retrieval service",
  "DashVector exposes its powerful vector management and query capabilities through simple, easy-to-use SDK/API interfaces, making it easy for upper-layer AI applications to integrate quickly",
  "This delivers the efficient vector retrieval capabilities required by a wide range of scenarios, including large model ecosystems, multimodal AI search, and molecular structure analysis",
  "A simple, flexible, out-of-the-box SDK that achieves vector management with minimal code",
  "In-house vector similarity algorithms deliver fast, efficient, and stable service",
  "Schema-free design that supports combined filtering queries under any conditions via Schema"
);

// Train the encoder on the full corpus
encoder.train(corpus);

Escolha o codificador adequado

Codificador	Pontos fortes	Limitações	Mais indicado para
Integrado	Pronto para uso, boa generalização	Menor precisão em termos especializados	Texto de uso geral, prototipagem rápida
Corpus personalizado	Maior precisão para vocabulário especializado	Requer treinamento prévio com todo o corpus	Dados específicos de domínio com termos técnicos

Selecione o codificador com base nos requisitos do seu negócio. Recomendamos criar um codificador baseado em seu próprio corpus caso sua aplicação envolva um grande número de termos específicos de um determinado campo.

Etapa 3: Codifique e insira um documento

Codifique o texto do documento em um vetor esparso com encode_documents e insira-o na coleção junto com um vetor denso.

Python

from dashvector import Doc

document = "DashVector is a vector retrieval service built on Proxima, Alibaba Cloud's in-house high-performance vector engine, offering a cloud-native, fully managed, and horizontally scalable vector retrieval service."
doc_sparse_vector = encoder.encode_documents(document)

print(doc_sparse_vector)
# Output based on the built-in encoder:
# {380823393: 0.7262431704356519, 414191989: 0.7262431704356519, 565176162: 0.7262431704356519, 904594806: 0.7262431704356519, 1005505802: 0.7262431704356519, 1169440797: 0.8883757984694465, 1240922502: 0.7262431704356519, 1313971048: 0.7262431704356519, 1317077351: 0.7262431704356519, 1490140460: 0.7262431704356519, 1574737055: 0.7262431704356519, 1760434515: 0.7262431704356519, 2045788977: 0.8414146776926797, 2141666983: 0.7262431704356519, 2509543087: 0.7262431704356519, 3180265193: 0.7262431704356519, 3845702398: 0.7262431704356519, 4106887295: 0.7262431704356519}

collection.insert(Doc(
    id='A',
    vector=[0.1, 0.2, 0.3, 0.4],
    sparse_vector=doc_sparse_vector
))

Java

String document = "DashVector is a vector retrieval service built on Proxima, DAMO Academy's in-house high-performance vector engine, offering a cloud-native, fully managed, and horizontally scalable vector retrieval service.";
Map<Long, Float> sparseVector = encoder.encodeDocuments(document);

System.out.println(sparseVector);
// Output based on the built-in encoder:
// {380823393: 0.7262431704356519, 414191989: 0.7262431704356519, 565176162: 0.7262431704356519, 904594806: 0.7262431704356519, 1005505802: 0.7262431704356519, 1169440797: 0.8883757984694465, 1240922502: 0.7262431704356519, 1313971048: 0.7262431704356519, 1317077351: 0.7262431704356519, 1490140460: 0.7262431704356519, 1574737055: 0.7262431704356519, 1760434515: 0.7262431704356519, 2045788977: 0.8414146776926797, 2141666983: 0.7262431704356519, 2509543087: 0.7262431704356519, 3180265193: 0.7262431704356519, 3845702398: 0.7262431704356519, 4106887295: 0.7262431704356519}

Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();

// Build a Doc with both dense and sparse vectors
Doc doc = Doc.builder()
  .id("28")
  .sparseVector(sparseVector)
  .vector(vector)
  .build();

// Insert the document
Response<Void> response = collection.insert(InsertDocRequest.builder().doc(doc).build());

Cada vetor esparso é um mapa de IDs de hash de tokens para pesos BM25. Pesos maiores indicam termos mais distintivos no documento.

Etapa 4: Execute uma busca semântica com reconhecimento de palavras-chave

Codifique a consulta de busca em um vetor esparso com encode_queries e passe os vetores densos e esparsos para query.

Python

query = "What is DashVector?"
sparse_vector = encoder.encode_queries(query)

print(sparse_vector)
# Output based on the built-in encoder:
# {1169440797: 0.2947158712590364, 2045788977: 0.7052841287409635}

docs = collection.query(
    vector=[0.1, 0.1, 0.1, 0.1],
    sparse_vector=sparse_vector
)

Java

String query = "What is DashVector?";

Map<Long, Float> sparseVector = encoder.encodeQueries(query);

System.out.println(sparseVector);
// Output based on the built-in encoder:
// {1169440797: 0.2947158712590364, 2045788977: 0.7052841287409635}

Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();

// Build a query with both dense and sparse vectors
QueryDocRequest request = QueryDocRequest.builder()
  .vector(vector)
  .sparse_ector(sparseVector)
  .topk(100)
  .includeVector(true)
  .build();

Response<List<Doc>> response = collection.query(request);
System.out.println(response);

Etapa 5: Ajuste os resultados com vetores ponderados

Controle o equilíbrio entre similaridade semântica (vetores densos) e correspondência de palavras-chave (vetores esparsos) usando o parâmetro alpha:

Valor de alpha	Comportamento
`0.0`	Apenas vetores esparsos são usados para medição de distância (busca pura por palavras-chave)
`1.0`	Apenas vetores densos são usados para medição de distância (busca puramente semântica)

Aplique combine_dense_and_sparse para escalonar ambos os vetores antes da consulta:

Python

from dashtext import combine_dense_and_sparse

query = "What is DashVector?"
sparse_vector = encoder.encode_queries(query)

# Set alpha to control the balance: 0.0 = keywords only, 1.0 = semantics only
alpha = 0.7
dense_vector = [0.1, 0.1, 0.1, 0.1]
scaled_dense_vector, scaled_sparse_vector = combine_dense_and_sparse(dense_vector, sparse_vector, alpha)

docs = collection.query(
    vector=scaled_dense_vector,
    sparse_vector=scaled_sparse_vector
)

Java

String query = "What is DashVector?";

Map<Long, Float> sparseVector = encoder.encodeQueries(query);

System.out.println(sparseVector);
// Output based on the built-in encoder:
// {1169440797: 0.2947158712590364, 2045788977: 0.7052841287409635}

Vector denseVector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();

// Scale dense and sparse vectors by the alpha weight factor
float alpha = 0.1f;
sparseVector.forEach((key, value) -> sparseVector.put(key, value * alpha));
denseVector = Vector.builder().value(
            denseVector.getValue().stream().map(number -> number.floatValue() * alpha).collect(Collectors.toList())
    ).build();

// Query with weighted vectors
QueryDocRequest request = QueryDocRequest.builder()
  .vector(denseVector)
  .sparse_ector(sparseVector)
  .topk(100)
  .includeVector(true)
  .build();

Response<List<Doc>> response = collection.query(request);
System.out.println(response);

Referência da API

Para a API completa do DashText, consulte o SDK do DashText para Python.