Todos os produtos
Search

Este produto

    Object Storage Service:Gerencie vetores com o OSS Vectors Embed CLI

    Central de documentação

    Object Storage Service:Gerencie vetores com o OSS Vectors Embed CLI

    Última atualização: Sep 22, 2026

    O OSS Vectors Embed CLI permite chamar os modelos de vetores do Alibaba Cloud Model Studio, vetorizar dados do OSS ou de arquivos locais, gravar os vetores em um vector bucket do OSS e realizar buscas semânticas multimodais. Isso simplifica o desenvolvimento de aplicações como bases de conhecimento RAG e assistentes de IA. Os principais recursos incluem:

    • Integração perfeita: chame o Alibaba Cloud Model Studio com facilidade para vetorizar dados.

    • Múltiplas fontes de entrada: vetorize dados de arquivos locais, objetos do OSS, URLs de arquivos de terceiros e strings de texto.

    • Processamento flexível: processe arquivos individuais ou execute a vetorização em lote de diretórios.

    • Personalização avançada: configure chaves de vetor e metadados escalares.

    • Busca multimodal: use textos, imagens e vídeos para busca de similaridade semântica, com suporte a diversos cenários de negócios.

    Com o OSS Vectors Embed CLI, você constrói rapidamente um sistema de busca semântica multimodal usando apenas alguns comandos. Além disso, é possível personalizá-lo com recursos como gravação em lote, chaves de vetor personalizadas e parâmetros de modelo.

    O Alibaba Cloud OSS Vectors Embed CLI está em versão de pré-visualização e seus parâmetros estão sujeitos a alterações.

    Etapa 1: Prepare seu ambiente

    Antes de usar a ferramenta CLI, prepare as seguintes credenciais de acesso:

    Configure as credenciais de acesso

    Defina suas credenciais de acesso como variáveis de ambiente. A CLI lê essas variáveis automaticamente durante a execução, permitindo que você as omita dos seus comandos.

    # Alibaba Cloud account AccessKey 
export OSS_ACCESS_KEY_ID="<your-access-key-id>"
export OSS_ACCESS_KEY_SECRET="<your-access-key-secret>"

# Model Studio API key
export DASHSCOPE_API_KEY="<your-dashscope-api-key>"
    Dica de segurança : Use variáveis de ambiente em vez de codificar as credenciais diretamente nos scripts.

    Instale o OSS Vectors Embed CLI

    Requer Python 3.9 ou superior.

    Método 1: Instale usando o pip (recomendado)

    pip install oss-vectors-embed-cli

    Método 2: Instale no modo de desenvolvedor

    git clone https://github.com/aliyun/oss-vectors-embed-cli.git
cd oss-vectors-embed-cli
pip install -e .

    Verifique a instalação

    oss-vectors-embed --version
# Output: oss-vectors-embed, version 0.1.0

    Crie um vector bucket

    Para gravar dados de vetor, primeiro crie um vector bucket e configure um índice:

    1. Crie um vector bucket: na página Vector Bucket, crie um bucket para armazenar seus dados de vetor e índices.

    2. Crie um índice de vetor: no novo bucket, crie um índice e defina sua dimensão de vetor para corresponder à dimensão de saída do seu modelo de vetor.

    Importante : A dimensão do índice de vetor deve corresponder à dimensão de saída do vector model que você utiliza. Por exemplo, se você usar o modelo text-embedding-v4 , que possui 1024 dimensões por padrão, a dimensão do índice também deve ser definida como 1024.

    Etapa 2: Grave os embeddings

    O OSS Vectors fornece a API PutVectors para gravar dados de vetor em um vector bucket do OSS. O OSS Vectors Embed CLI simplifica esse processo ao agrupar várias chamadas de API — leitura do arquivo de origem (GetObject), geração de um embedding com o Alibaba Cloud Model Studio (Bailian) e gravação dos dados de vetor (PutVectors) — em um único comando put. Cada arquivo é processado como um único embedding. O fatiamento automático de documentos longos não é suportado no momento.

    Gere embeddings a partir de arquivos de texto

    Use um text embedding model, como o text-embedding-v4, para processar texto. As fontes de entrada suportadas incluem strings de texto, objetos do OSS e arquivos de texto locais.

    Use uma string de texto como entrada

    Gere um embedding a partir de uma string de texto inline e grave-o no seu vector bucket do OSS:

    # Parameter descriptions:
# --account-id:         Alibaba Cloud account ID
# --vectors-region:     Region of the OSS vector bucket
# --vector-bucket-name: Name of the OSS vector bucket
# --index-name:         Name of the OSS vector index
# --model-id:           The embedding model to use
# --text-value:         The input text string

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "Artificial intelligence is changing the way we live"

    Resposta de exemplo:

    {
  "key": "3d8935dd-6395-4c9c-a501-df902846ec80",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "Artificial intelligence is changing the way we live",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

    Nota: A CLI adiciona automaticamente campos OSSVECTORS-EMBED-SRC-* aos metadados para rastrear a origem do embedding.

    Use um arquivo de texto local como entrada

    Gere um embedding a partir de um arquivo local e grave-o no seu vector bucket do OSS:

    # Parameter descriptions:
# --account-id:         Alibaba Cloud account ID
# --vectors-region:     Region of the OSS vector bucket
# --vector-bucket-name: Name of the OSS vector bucket
# --index-name:         Name of the OSS vector index
# --model-id:           The embedding model to use
# --text:               Path to the local file

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "<./documents/article.txt>"

    Resposta de exemplo:

    {
  "key": "415c108e-d653-4d54-a241-d3b70e996666",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "Artificial intelligence is changing the way we live. From being gently woken up by a smart alarm clock based on our sleep cycle in the morning, to having a voice assistant plan the best route for our commute; from a smart speaker at home playing personalized news summaries, to AI tools at work automatically generating reports, translating documents, and optimizing workflows—AI has quietly integrated into every corner of our daily lives.",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "./documents/article.txt"
  }
}

    Use um objeto do OSS como entrada

    Gere um embedding a partir de um objeto armazenado no OSS e grave-o no seu vector bucket do OSS. O caminho do objeto deve estar no formato oss://bucket-name/object-key.

    # Parameter descriptions:
# --account-id:         Alibaba Cloud account ID
# --vectors-region:     Region of the OSS vector bucket
# --vector-bucket-name: Name of the OSS vector bucket
# --index-name:         Name of the OSS vector index
# --model-id:           The embedding model to use
# --region:             Region of the source object's bucket
# --text:               OSS path of the source file

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --region cn-hangzhou \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "oss://<your-source-bucket>/<your-file>"

    Nota: Você deve usar o parâmetro --region para especificar a região do objeto do OSS de origem.

    Resposta de exemplo:

    {
  "key": "7ca24758-0d5b-46fe-ab90-db82be387650",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "This is an example file.",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/documents/file.txt"
  }
}

    Gere embeddings a partir de arquivos de imagem

    Use um multimodal embedding model, como o qwen2.5-vl-embedding, para processar imagens e vídeos. As fontes de entrada suportadas incluem arquivos locais, objetos do OSS e URLs HTTP/HTTPS.

    Use uma imagem local como entrada

    Gere um embedding a partir de um arquivo de imagem local e grave-o no seu vector bucket do OSS:

    # Parameter descriptions:
# --account-id:         Alibaba Cloud account ID
# --vectors-region:     Region of the OSS vector bucket
# --vector-bucket-name: Name of the OSS vector bucket
# --index-name:         Name of the OSS vector index
# --model-id:           The embedding model to use
# --image:              Path to the local image file

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "<./images/photo.jpg>"

    Resposta de exemplo:

    {
  "key": "8fc8105b-d54f-464c-bf44-97b088d566ce",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "image",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "./images/photo.jpg",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

    Use um objeto do OSS como entrada

    Gere um embedding a partir de uma imagem armazenada em um objeto do OSS e grave-o no seu vector bucket do OSS. O caminho do objeto deve estar no formato oss://bucket-name/object-key.

    # Parameter descriptions:
# --account-id:         Alibaba Cloud account ID
# --vectors-region:     Region of the OSS vector bucket
# --vector-bucket-name: Name of the OSS vector bucket
# --index-name:         Name of the OSS vector index
# --model-id:           The embedding model to use
# --region:             Region of the source object's bucket
# --image:              OSS path of the source image

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --region cn-hangzhou \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "oss://<your-source-bucket>/<your-image>"

    Resposta de exemplo:

    {
  "key": "dbf57dfd-58be-4793-a484-a82eb86e0e08",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "image",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/photo.jpg",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

    Use uma URL de imagem como entrada

    Gere um embedding a partir de uma imagem em uma URL e grave-o no seu vector bucket do OSS:

    # Parameter descriptions:
# --account-id:         Alibaba Cloud account ID
# --vectors-region:     Region of the OSS vector bucket
# --vector-bucket-name: Name of the OSS vector bucket
# --index-name:         Name of the OSS vector index
# --model-id:           The embedding model to use
# --image:              URL of the image

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "https://example.com/photo.jpg"

    Resposta de exemplo:

    {
  "key": "f15cfe75-d4de-497f-b441-3b08243cfa5e",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "image",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "https://example.com/photo.jpg",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE"
  }
}

    Gere embeddings a partir de arquivos de vídeo

    Use um multimodal embedding model, como o qwen2.5-vl-embedding, para processar vídeos. As fontes de entrada suportadas são arquivos de vídeo do OSS e URLs HTTP/HTTPS. Ao processar um vídeo, a CLI extrai os quadros-chave e gera um embedding separado para cada quadro. Como cada embedding requer uma chave exclusiva, os parâmetros --key e --filename-as-key não são suportados. A CLI gera automaticamente uma chave sequencial exclusiva para cada quadro.

    Use um objeto do OSS como entrada

    Gere embeddings a partir de um arquivo de vídeo do OSS (o que envolve criar uma URL pré-assinada para acesso) e grave-os no seu vector bucket do OSS:

    # Parameter descriptions:
# --account-id:         Alibaba Cloud account ID
# --vectors-region:     Region of the OSS vector bucket
# --vector-bucket-name: Name of the OSS vector bucket
# --index-name:         Name of the OSS vector index
# --model-id:           The embedding model to use
# --region:             Region of the source video's bucket
# --video:              OSS path of the source video
# --presign-url:        Generates a presigned URL for the OSS path to grant access (for private buckets and similar scenarios).

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --region cn-hangzhou \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --video "oss://<your-source-bucket>/<your-video>" \
  --presign-url

    Resposta de exemplo:

    {
  "key": "55606734-8275-4329-96a3-3c156220et54",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "video",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/video.mp4",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "VIDEO"
  }
}

    Use uma URL de vídeo como entrada

    Gere embeddings a partir de um vídeo em uma URL e grave-os no seu vector bucket do OSS:

    # Parameter descriptions:
# --account-id:         Alibaba Cloud account ID
# --vectors-region:     Region of the OSS vector bucket
# --vector-bucket-name: Name of the OSS vector bucket
# --index-name:         Name of the OSS vector index
# --model-id:           The embedding model to use
# --video:              URL of the video

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --video "https://example.com/video.mp4"

    Resposta de exemplo:

    {
  "key": "9157d87b-c44b-4c53-aceb-cd4be7fd8bd9",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "qwen2.5-vl-embedding",
  "contentType": "video",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-LOCATION": "https://example.com/video.mp4",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "VIDEO"
  }
}

    Adicione metadados escalares durante a gravação

    Você pode anexar metadados escalares personalizados ao gravar um embedding. Esses dados podem ser usados posteriormente em consultas filtradas.

    oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "Technical document content" \
  --metadata '{"category": "technology", "version": "1.0", "author": "admin"}' # Add custom scalar metadata for filtered queries

    Os campos de metadados definidos pelo usuário são mesclados com os campos do sistema gerados automaticamente. Resposta de exemplo:

    {
  "key": "c0ed4d9d-5301-49a5-82b7-eaf9d02b04a9",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "category": "technology",  // Custom metadata
    "version": "1.0",          // Custom metadata
    "author": "admin",         // Custom metadata
    "OSSVECTORS-EMBED-SRC-CONTENT": "Technical document content",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

    Etapa 3: Busca de vetores

    O OSS Vectors fornece a API QueryVectors para realizar uma busca por similaridade. O oss-vectors-embed-cli disponibiliza o comando query para executar essa busca. Esse comando primeiro vetoriza o conteúdo da consulta (texto ou imagem) e, em seguida, encontra os vetores semanticamente mais semelhantes no índice de vetor.

    Importante : O modelo de vetor usado para a consulta deve corresponder ao modelo usado para indexar os dados.

    Busca de similaridade de texto

    Consulte vetores semanticamente semelhantes com base em uma entrada de texto. O parâmetro --top-k controla o número de resultados a serem retornados. Execute o seguinte comando para buscar no índice de vetor my-index os vetores semanticamente semelhantes a "What is artificial intelligence".

    # --text-value: The query text.
# --top-k:      The number of most similar vectors to return.

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "What is artificial intelligence" \
  --top-k 100

    Saída de exemplo (inclui a chave do vetor e os metadados):

    {
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSSVECTORS-EMBED-SRC-CONTENT": "Artificial intelligence is changing our way of life",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 100,
    "queryDimensions": 1024
  }
}

    Nota: A distância de similaridade não é retornada por padrão. Para incluí-la nos resultados, adicione o parâmetro --return-distance.

    Busca de similaridade de imagem

    Encontre os vetores mais semelhantes com base em uma consulta de imagem. Isso atende a casos de uso como busca de imagem por imagem.

    # --image:  The query image.
# --top-k:  The number of most similar vectors to return.

oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --image "./query-images/similar-product.jpg" \   
  --top-k 100

    Saída de exemplo (inclui a chave do vetor e os metadados):

    {
  "results": [
    {
      "Key": "11dcf66b-708a-4707-8bd4-8656bead19da",          // A search result, containing the vector key and metadata.
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "IMAGE",
        "OSSVECTORS-EMBED-SRC-LOCATION": "similar-product.png"
      }
    },
    {
    ...
  ],
  "summary": {
    "queryType": "image",
    "model": "qwen2.5-vl-embedding",
    "index": "my-index",
    "resultsFound": 100,
    "queryDimensions": 1024
  }
}

    Busca filtrada por metadados

    Use o parâmetro --filter para realizar a pós-filtragem de metadados. Isso restringe o escopo da busca e fornece resultados mais precisos. O oss-vectors-embed-cli suporta filtragem simples com base em um único campo de metadados e filtragem combinada usando múltiplas condições.

    Filtragem simples

    Consulte vetores em que a category seja technology:

    # --filter: Performs filtering based on scalar metadata.
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "Technical documentation" \
  --filter '{"category": {"$eq": "technology"}}' \
  --top-k 20 \
  --return-metadata

    Nota: O parâmetro --return-metadata retorna os metadados completos nos resultados, incluindo tanto os campos definidos pelo usuário quanto aqueles adicionados automaticamente pela CLI.

    Saída de exemplo:

    {
  "results": [
    {
      "Key": "fd91808c-8d7c-480e-a72b-2bfa7d313a80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "author": "admin",
        "category": "technology",
        "OSSVECTORS-EMBED-SRC-CONTENT": "Technical document content",
        "version": "1.0",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "test1",
    "resultsFound": 4,
    "queryDimensions": 1024
  }
}

    Filtragem combinada

    O oss-vectors-embed-cli permite combinar múltiplas condições de filtro, como AND e OR, com base no filter syntax. O exemplo a seguir mostra uma condição AND.

    Consulta AND: corresponde a todas as condições.

    # AND: Both conditions must match.
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "API Reference" \
  --filter '{"$and": [{"category": "documentation"}, {"version": "3.0"}]}' \
  --top-k 5

    Saída de exemplo:

    {
  "results": [
  {
      "Key": "fd91808c-8d7c-480e-a72b-2bfa7d313a80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "author": "admin",
        "category": "documentation",
        "OSSVECTORS-EMBED-SRC-CONTENT": "API Reference",
        "version": "3.0",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    {
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 5,
    "queryDimensions": 1024
  }
}

    Para exibir os resultados da busca em formato de tabela, use o parâmetro --output table. Isso converte a saída JSON padrão em uma tabela, facilitando a revisão manual, a exploração interativa e a depuração.

    # --output table: Specifies the output format as a table.
oss-vectors-embed \
--account-id <your-account-id> \
--vectors-region cn-hangzhou \
query \
--vector-bucket-name <your-vector-bucket> \
--index-name <your-index> \
--model-id text-embedding-v4 \
--text "./queries/user-question.txt" \
--top-k 3 \
--output table

    Saída de exemplo:

                                     Query Results
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Rank ┃ Vector Key             ┃ Distance ┃ Metadata               ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1    │ doc:auth-setup         │ N/A      │ {"category": "docs"}   │
│ 2    │ doc:security-config    │ N/A      │ {"category": "docs"}   │
│ 3    │ doc:api-reference      │ N/A      │ {"category": "docs"}   │
└──────┴────────────────────────┴──────────┴────────────────────────┘
Query Summary:
  Model: text-embedding-v4
  Results Found: 3
  Query Dimensions: 1024

    Nota: A coluna Distance mostra N/A porque o comando não inclui o parâmetro --return-distance. Adicione esse parâmetro para exibir os valores de distância.

    Configuração avançada

    Processamento em lote

    A CLI suporta o processamento em lote de todos os arquivos em um diretório usando um curinga. No modo em lote, a CLI envia automaticamente solicitações paralelas para melhorar o throughput. O exemplo a seguir usa um curinga para processar em lote todos os arquivos sob um prefixo específico em um bucket do OSS.

    # Use --text "oss://bucket/path/*" to batch vectorize and write the vector results for all files under the specified prefix.
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "oss://bucket/path/*"

    Resposta de exemplo:

    {
  "type": "streaming_batch",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "totalFiles": 2,
  "processedFiles": 2,
  "failedFiles": 0,
  "totalVectors": 2,
  "vectorKeys": [
    "1001dfcb-1e78-450b-8526-a9c92fa308c6",
    "b6aa1da0-adc7-489e-83e2-e39ff2e1fb9d"
  ]
}

    Para o processamento em lote, use o parâmetro --max-workers para controlar a simultaneidade (o padrão é 4). Aumentar esse valor pode melhorar o throughput, mas consome mais cota de API. O OSS Vectors suporta a gravação de até 500 vetores por solicitação em lote e permite no máximo 5 solicitações simultâneas.

    # --max-workers: Set the concurrency.
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "./documents/*.txt" \
  --max-workers 5

    Resposta de exemplo:

    {
  "type": "streaming_batch",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "totalFiles": 5,
  "processedFiles": 5,
  "failedFiles": 0,
  "totalVectors": 5,
  "vectorKeys": [
    "doc1.txt",
    "doc2.txt",
    "doc3.txt",
    "doc4.txt",
    "doc5.txt"
  ]
}

    Personalize as chaves de vetor

    A CLI oferece opções flexíveis para especificar a chave do vetor. Você pode definir uma string personalizada, usar o nome original do arquivo ou adicionar um prefixo a todas as chaves.

    Chave personalizada

    Use o parâmetro --key para definir a chave do vetor com um valor específico:

    # Set the vector key to "doc-001".
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "Document content" \
  --key "doc-001"

    Resposta de exemplo:

    {
 "key": "doc-001",    // The vector key is "doc-001".
 "bucket": "my-test-2",
 "index": "test1",
 "model": "text-embedding-v4",
 "contentType": "text",
 "embeddingDimensions": 1024,
 "metadata": {
   "OSSVECTORS-EMBED-SRC-CONTENT": "Document content",
   "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}

    Nome do arquivo como chave

    Use o parâmetro --filename-as-key para usar automaticamente o nome do arquivo como a chave do vetor:

    # Use the filename "article.txt" as the vector key.
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text "article.txt" \
  --filename-as-key

    Resposta de exemplo:

    {
  "key": "article.txt",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "Artificial intelligence is changing the way we live. From being gently woken up by a smart alarm clock based on our sleep cycle in the morning, to having a voice assistant plan the best route for our commute; from a smart speaker at home playing personalized news summaries, to AI tools at work automatically generating reports, translating documents, and optimizing workflows—AI has quietly integrated into every corner of our daily lives.",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "article.txt"
  }
}

    Prefixo da chave

    # --key-prefix: Add a prefix to the vector key.
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "Document content" \
  --key "doc-001" \
  --key-prefix "project-a/"

    Resposta de exemplo:

    {
  "key": "project-a/doc-001",    // The vector key is prefixed with "project-a/".
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "Document content",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

    Personalize os parâmetros do modelo

    Use o parâmetro --dashscope-inference-params para ajustar o modelo de vetor para diferentes cenários de negócios.

    Grave com parâmetros personalizados

    Ao vetorizar dados, especifique parâmetros como o tipo de saída e a dimensão:

    # Use --dashscope-inference-params '{"output_type": "dense", "dimension": "1024"}' to customize the model's output type and vector dimension.
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  put \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id text-embedding-v4 \
  --text-value "Technical document content" \
  --dashscope-inference-params '{"output_type": "dense", "dimension": "1024"}'

    Resposta de exemplo:

    {
 "key": "73359c62-55a7-458a-a171-003755f3338e",
 "bucket": "my-vector-bucket",
 "index": "my-index",
 "model": "text-embedding-v4",
 "contentType": "text",
 "embeddingDimensions": 1024,
 "metadata": {
   "OSSVECTORS-EMBED-SRC-CONTENT": "Document content",
   "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}

    Consulte com parâmetros personalizados

    Ao consultar vetores, controle comportamentos como a política de truncamento de texto:

    # Use --dashscope-inference-params '{"truncate": "END"}' to set the text truncation policy.
oss-vectors-embed \
  --account-id <your-account-id> \
  --vectors-region cn-hangzhou \
  query \
  --vector-bucket-name <your-vector-bucket> \
  --index-name <your-index> \
  --model-id qwen2.5-vl-embedding \
  --text-value "Technical documentation" \
  --dashscope-inference-params '{"truncate": "END"}' \
  --top-k 10
  --return-distance

    Resposta de exemplo:

    {
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSSVECTORS-EMBED-SRC-CONTENT": "Technical documentation",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "qwen2.5-vl-embedding",
    "index": "my-index",
    "resultsFound": 10,
    "queryDimensions": 1024
  }
}

    Modelos de embedding suportados

    Modelos de embedding de texto

    ID do modelo

    Dimensões padrão

    Dimensões opcionais

    text-embedding-v4

    1024

    2048/1536/768/512/256/128/64

    text-embedding-v3

    1024

    768/512/256/128/64

    text-embedding-v2

    1536

    -

    text-embedding-v1

    1536

    -

    Modelos de embedding multimodal

    ID do modelo

    Dimensões

    Tipos de entrada suportados

    qwen2.5-vl-embedding

    2048/1024/768/512

    texto, imagem, vídeo, múltiplas imagens

    tongyi-embedding-vision-plus

    1152

    texto, imagem, vídeo, múltiplas imagens

    tongyi-embedding-vision-flash

    768

    texto, imagem, vídeo, múltiplas imagens

    multimodal-embedding-v1

    1024

    texto, imagem, vídeo

    Recomendações para seleção de modelos:

    • Para casos de uso apenas com texto, use o text-embedding-v4.

    • Para casos de uso com texto e imagem misturados, use o qwen2.5-vl-embedding.

    • Para casos de uso com baixa latência, considere o tongyi-embedding-vision-flash.

    Parâmetros

    Parâmetros globais

    Parâmetro

    Obrigatório

    Descrição

    --account-id

    Sim

    O ID da sua conta Alibaba Cloud.

    --vectors-region

    Sim

    A região onde o vector bucket está localizado, por exemplo, cn-hangzhou.

    --vectors-endpoint

    Não

    O endpoint para o vector bucket.

    --debug

    Não

    Ativa o modo de depuração.

    Parâmetros do comando put

    Parâmetro

    Obrigatório

    Descrição

    --vector-bucket-name

    Sim

    O nome do vector bucket.

    --index-name

    Sim

    O nome do índice de vetor.

    --model-id

    Sim

    Especifica o ID do DashScope model para gerar embeddings.

    --text-value

    Não

    O texto a ser processado. Você deve especificar um entre --text-value, --text, --image ou --video.

    --text

    Não

    O caminho para um arquivo de texto ou um objeto do OSS a ser processado.

    --image

    Não

    O caminho para um arquivo de imagem, um objeto do OSS ou uma URL a ser processada.

    --video

    Não

    A URL do vídeo a ser processado.

    --key

    Não

    Especifica uma chave exclusiva personalizada para o vetor.

    --key-prefix

    Não

    Adiciona um prefixo à chave gerada automaticamente ou especificada.

    --filename-as-key

    Não

    Usa o nome do arquivo de entrada como a chave do vetor.

    --dashscope-inference-params

    Não

    Especifica parâmetros específicos do modelo para passar ao DashScope no formato JSON, por exemplo, '{"dimension": "1024"}'.

    --metadata

    Não

    Os metadados para o vetor, especificados como uma string JSON.

    --max-workers

    Não

    O número máximo de solicitações simultâneas para processamento em lote. Padrão: 4.

    --batch-size

    Não

    O número de vetores a serem incluídos em cada solicitação durante uma gravação em lote. Intervalo de valores: 1–500. Padrão: 500.

    --output

    Não

    Especifica o formato de saída. Os valores válidos são json (padrão) ou table.

    --region

    Não

    Se a entrada for um objeto do OSS, este parâmetro especifica a região do objeto.

    --presign-url

    Não

    Gera uma URL pré-assinada para acessar o objeto do OSS de entrada.

    Parâmetros do comando query

    Parâmetro

    Obrigatório

    Descrição

    --vector-bucket-name

    Sim

    O nome do vector bucket.

    --index-name

    Sim

    O nome do índice de vetor.

    --model-id

    Sim

    Especifica o ID do DashScope model para gerar embeddings.

    --text-value

    Não

    O texto da consulta.

    --text

    Não

    O caminho para um arquivo que contém o texto da consulta.

    --image

    Não

    O caminho para a imagem a ser consultada.

    --video

    Não

    A URL do vídeo a ser consultado.

    --top-k

    Não

    O número de resultados mais semelhantes a serem retornados. Padrão: 5.

    --filter

    Não

    Os critérios de filtro, especificados como uma string JSON.

    --return-distance

    Não

    Inclui a distância de similaridade nos resultados.

    --return-metadata

    Não

    Inclui metadados nos resultados. Ativado por padrão.

    --dashscope-inference-params

    Não

    Especifica parâmetros específicos do modelo para passar ao DashScope no formato JSON, por exemplo, '{"truncate": "END"}'.

    --output

    Não

    Especifica o formato de saída. Os valores válidos são json (padrão) ou table.

    Sintaxe de filtro

    Operador

    Descrição

    Exemplo

    $eq

    Igual a

    {"category": {"$eq": "docs"}}

    $ne

    Diferente de

    {"status": {"$ne": "deleted"}}

    $in/$nin

    Está ou não está em uma lista especificada

    {"tag": {"$in": ["a", "b"]}}

    $and

    AND lógico

    {"$and": [{"a": 1}, {"b": 2}]}

    $or

    OR lógico

    {"$or": [{"a": 1}, {"a": 2}]}

    Referências

    Para mais informações sobre o OSS Vectors Embed CLI, consulte o repositório no GitHub.