OSS Vectors Embed CLI - write and retrieve vector data - Object Storage Service

Étape 1 : Préparer votre environnement

Avant d'utiliser l'outil CLI, préparez les informations d'identification d'accès suivantes :

Configurer les informations d'identification d'accès

Définissez vos informations d'identification d'accès en tant que variables d'environnement. La CLI lit automatiquement ces variables lors de son exécution, ce qui vous permet de les omettre dans vos commandes.

# 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>"

Conseil de sécurité : Utilisez des variables d'environnement au lieu d'intégrer directement les informations d'identification dans les scripts.

Installer OSS Vectors Embed CLI

Nécessite Python 3.9 ou une version ultérieure.

Méthode 1 : Installer via pip (recommandé)

pip install oss-vectors-embed-cli

Méthode 2 : Installer en mode développeur

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

Vérifier l'installation

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

Créer un compartiment de vecteurs

Pour écrire des données vectorielles, commencez par créer un compartiment de vecteurs et configurer un index :

Créer un compartiment de vecteurs : Sur la page Vector Bucket, créez un compartiment pour stocker vos données vectorielles et vos index.
Créer un index de vecteurs : Dans le nouveau compartiment, créez un index et définissez sa dimension de vecteur pour qu'elle corresponde à la dimension de sortie de votre modèle de vecteur.

Important : La dimension de l'index de vecteurs doit correspondre à la dimension de sortie du modèle de vecteur que vous utilisez. Par exemple, si vous utilisez le modèle text-embedding-v4 , dont la dimension par défaut est 1024, la dimension de l'index doit également être définie sur 1024.

Étape 2 : Écrire les embeddings

OSS Vectors fournit l'API PutVectors pour écrire des données vectorielles dans un compartiment de vecteurs OSS. OSS Vectors Embed CLI simplifie ce processus en regroupant plusieurs appels d'API — lecture du fichier source (GetObject), génération d'un embedding avec Alibaba Cloud Model Studio (Bailian) et écriture des données vectorielles (PutVectors) — en une seule commande put. Chaque fichier est traité comme un seul embedding. Le découpage automatique pour les documents longs n'est pas pris en charge actuellement.

Générer des embeddings à partir de fichiers texte

Utilisez un modèle d'embedding de texte, tel que text-embedding-v4, pour traiter le texte. Les sources d'entrée prises en charge incluent les chaînes de texte, les objets OSS et les fichiers texte locaux.

Utiliser une chaîne de texte comme entrée

Générez un embedding à partir d'une chaîne de texte intégrée et écrivez-le dans votre compartiment de vecteurs 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"

Exemple de réponse :

{
  "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"
  }
}

Remarque : La CLI ajoute automatiquement des champs OSSVECTORS-EMBED-SRC-* aux métadonnées pour tracer la source de l'embedding.

Utiliser un fichier texte local comme entrée

Générez un embedding à partir d'un fichier local et écrivez-le dans votre compartiment de vecteurs 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>"

Exemple de réponse :

{
  "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"
  }
}

Utiliser un objet OSS comme entrée

Générez un embedding à partir d'un objet stocké dans OSS et écrivez-le dans votre compartiment de vecteurs OSS. Le chemin de l'objet doit être au format 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>"

Remarque : Vous devez utiliser le paramètre --region pour spécifier la région de l'objet OSS source.

Exemple de réponse :

{
  "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"
  }
}

Générer des embeddings à partir de fichiers image

Utilisez un modèle d'embedding multimodal, tel que qwen2.5-vl-embedding, pour traiter les images et les vidéos. Les sources d'entrée prises en charge incluent les fichiers locaux, les objets OSS et les URL HTTP/HTTPS.

Utiliser une image locale comme entrée

Générez un embedding à partir d'un fichier image local et écrivez-le dans votre compartiment de vecteurs 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>"

Exemple de réponse :

{
  "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"
  }
}

Utiliser un objet OSS comme entrée

Générez un embedding à partir d'une image stockée dans un objet OSS et écrivez-le dans votre compartiment de vecteurs OSS. Le chemin de l'objet doit être au format 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>"

Exemple de réponse :

{
  "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"
  }
}

Utiliser une URL d'image comme entrée

Générez un embedding à partir d'une image située à une URL et écrivez-le dans votre compartiment de vecteurs 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"

Exemple de réponse :

{
  "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"
  }
}

Générer des embeddings à partir de fichiers vidéo

Utilisez un modèle d'embedding multimodal, tel que qwen2.5-vl-embedding, pour traiter les vidéos. Les sources d'entrée prises en charge sont les fichiers vidéo OSS et les URL HTTP/HTTPS. Lors du traitement d'une vidéo, la CLI extrait les images clés et génère un embedding distinct pour chaque image. Étant donné que chaque embedding nécessite une clé unique, les paramètres --key et --filename-as-key ne sont pas pris en charge. La CLI génère automatiquement une clé séquentielle unique pour chaque image.

Utiliser un objet OSS comme entrée

Générez des embeddings à partir d'un fichier vidéo OSS (ce qui implique la création d'une URL signée pour l'accès) et écrivez-les dans votre compartiment de vecteurs 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

Exemple de réponse :

{
  "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"
  }
}

Utiliser une URL vidéo comme entrée

Générez des embeddings à partir d'une vidéo située à une URL et écrivez-les dans votre compartiment de vecteurs 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"

Exemple de réponse :

{
  "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"
  }
}

Ajouter des métadonnées scalaires lors de l'écriture

Vous pouvez joindre des métadonnées scalaires personnalisées lors de l'écriture d'un embedding. Ces données peuvent ensuite être utilisées dans des requêtes filtrées.

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

Les champs de métadonnées définis par l'utilisateur sont fusionnés avec les champs système générés automatiquement. Exemple de réponse :

{
  "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"
  }
}

Étape 3 : Recherche vectorielle

OSS Vectors fournit l'API QueryVectors pour effectuer une recherche de similarité. oss-vectors-embed-cli propose la commande query pour exécuter une recherche de similarité. Cette commande vectorise d'abord le contenu de la requête (texte ou image), puis trouve les vecteurs les plus similaires sur le plan sémantique dans l'index de vecteurs.

Important : Le modèle de vecteur utilisé pour la requête doit correspondre au modèle utilisé pour indexer les données.

Recherche de similarité textuelle

Vous pouvez rechercher des vecteurs sémantiquement similaires en fonction d'une entrée textuelle. Le paramètre --top-k contrôle le nombre de résultats à renvoyer. Exécutez la commande suivante pour rechercher dans l'index de vecteurs my-index les vecteurs sémantiquement similaires à « 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

Exemple de sortie (inclut la clé du vecteur et les métadonnées) :

{
  "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
  }
}

Remarque : La distance de similarité n'est pas renvoyée par défaut. Pour l'inclure dans les résultats, ajoutez le paramètre --return-distance.

Recherche de similarité d'images

Vous pouvez trouver les vecteurs les plus similaires en fonction d'une requête d'image. Cela prend en charge des cas d'utilisation tels que la recherche d'image à image.

# --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

Exemple de sortie (inclut la clé du vecteur et les métadonnées) :

{
  "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
  }
}

Recherche filtrée par métadonnées

Vous pouvez utiliser le paramètre --filter pour effectuer un post-filtrage des métadonnées. Cela réduit la portée de la recherche et fournit des résultats plus précis. oss-vectors-embed-cli prend en charge le filtrage simple basé sur un seul champ de métadonnées et le filtrage combiné utilisant plusieurs conditions.

Filtrage simple

Recherchez des vecteurs où la category est 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

Remarque : Le paramètre --return-metadata renvoie les métadonnées complètes dans les résultats, y compris les champs définis par l'utilisateur et ceux ajoutés automatiquement par la CLI.

Exemple de sortie :

{
  "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
  }
}

Filtrage combiné

oss-vectors-embed-cli vous permet de combiner plusieurs conditions de filtre, telles que AND et OR, en fonction de la syntaxe de filtre. L'exemple suivant montre une condition AND.

Requête AND : Correspond à toutes les conditions.

# 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

Exemple de sortie :

{
  "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
  }
}

Pour afficher les résultats de recherche sous forme de tableau, utilisez le paramètre --output table. Cette option convertit la sortie JSON par défaut en un tableau, ce qui facilite la relecture manuelle, l'exploration interactive et le débogage.

# --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

Exemple de sortie :

                                 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

Remarque : La colonne Distance affiche N/A car la commande n'inclut pas le paramètre --return-distance. Ajoutez ce paramètre pour afficher les valeurs de distance.

Configuration avancée

Traitement par lots

L'interface CLI prend en charge le traitement par lots de tous les fichiers d'un répertoire à l'aide d'un caractère générique. En mode lot, l'interface CLI envoie automatiquement des requêtes parallèles pour améliorer le débit. L'exemple suivant utilise un caractère générique pour traiter par lots tous les fichiers situés sous un préfixe spécifique dans un bucket 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/*"

Exemple de réponse :

{
  "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"
  ]
}

Pour le traitement par lots, utilisez le paramètre --max-workers afin de contrôler la concurrence (la valeur par défaut est 4). L'augmentation de cette valeur peut améliorer le débit, mais consomme davantage de quota d'API. OSS Vectors permet d'écrire jusqu'à 500 vecteurs par requête par lot et autorise un maximum de 5 requêtes simultanées.

# --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

Exemple de réponse :

{
  "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"
  ]
}

Personnalisation des clés de vecteur

L'interface CLI offre des options flexibles pour spécifier la clé de vecteur. Vous pouvez définir une chaîne personnalisée, utiliser le nom de fichier d'origine ou ajouter un préfixe à toutes les clés.

Clé personnalisée

Utilisez le paramètre --key pour attribuer une valeur spécifique à la clé de vecteur :

# 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"

Exemple de réponse :

{
 "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"
 }
}

Nom de fichier comme clé

Utilisez le paramètre --filename-as-key pour utiliser automatiquement le nom du fichier comme clé de vecteur :

# 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

Exemple de réponse :

{
  "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"
  }
}

Préfixe de clé

# --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/"

Exemple de réponse :

{
  "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"
  }
}

Personnalisation des paramètres du modèle

Utilisez le paramètre --dashscope-inference-params pour affiner le modèle de vecteur selon différents scénarios métier.

Écriture avec des paramètres personnalisés

Lors de la vectorisation des données, spécifiez des paramètres tels que le type de sortie et la dimension :

# 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"}'

Exemple de réponse :

{
 "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"
 }
}

Requête avec des paramètres personnalisés

Lors de l'interrogation des vecteurs, vous pouvez contrôler des comportements tels que la politique de troncature du texte :

# 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

Exemple de réponse :

{
  "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
  }
}

Modèles d'embedding pris en charge

Modèles d'embedding de texte

ID du modèle

Dimensions par défaut

Dimensions facultatives

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

-

Modèles d'embedding multimodaux

ID du modèle

Dimensions

Types d'entrée pris en charge

qwen2,5-vl-embedding

2048/1024/768/512

texte, image, vidéo, plusieurs images

tongyi-embedding-vision-plus

1152

texte, image, vidéo, plusieurs images

tongyi-embedding-vision-flash

768

texte, image, vidéo, plusieurs images

multimodal-embedding-v1

1024

texte, image, vidéo

Recommandations de sélection de modèle :

Pour les cas d'utilisation exclusivement textuels, utilisez text-embedding-v4.
Pour les cas d'utilisation combinant texte et images, utilisez qwen2.5-vl-embedding.
Pour les cas d'utilisation nécessitant une faible latence, envisagez tongyi-embedding-vision-flash.

Paramètres

Paramètres globaux

Paramètre

Obligatoire

Description

--account-id

Oui

Votre ID de compte Alibaba Cloud.

--vectors-region

Oui

La région où se trouve le bucket de vecteurs, par exemple cn-hangzhou.

--vectors-endpoint

Non

L'endpoint du bucket de vecteurs.

--debug

Non

Active le mode débogage.

Paramètres de la commande put

Paramètre

Obligatoire

Description

--vector-bucket-name

Oui

Le nom du bucket de vecteurs.

--index-name

Oui

Le nom de l'index de vecteurs.

--model-id

Oui

Spécifie l'ID du modèle DashScope utilisé pour générer les embeddings.

--text-value

Non

Le texte à traiter. Vous devez spécifier l'un des paramètres suivants : --text-value, --text, --image ou --video.

--text

Non

Le chemin d'accès à un fichier texte ou à un objet OSS à traiter.

--image

Non

Le chemin d'accès à un fichier image, à un objet OSS ou une URL à traiter.

--video

Non

L'URL de la vidéo à traiter.

--key

Non

Spécifie une clé unique personnalisée pour le vecteur.

--key-prefix

Non

Ajoute un préfixe à la clé générée automatiquement ou spécifiée.

--filename-as-key

Non

Utilise le nom du fichier d'entrée comme clé de vecteur.

--dashscope-inference-params

Non

Spécifie les paramètres spécifiques au modèle à transmettre à DashScope au format JSON, par exemple '{"dimension": "1024"}'.

--metadata

Non

Les métadonnées du vecteur, spécifiées sous forme de chaîne JSON.

--max-workers

Non

Le nombre maximal de requêtes simultanées pour le traitement par lots. Valeur par défaut : 4.

--batch-size

Non

Le nombre de vecteurs à inclure dans chaque requête lors d'une écriture par lots. Plage de valeurs : 1–500. Valeur par défaut : 500.

--output

Non

Spécifie le format de sortie. Les valeurs valides sont json (par défaut) ou table.

--region

Non

Si l'entrée est un objet OSS, ce paramètre spécifie la région de l'objet.

--presign-url

Non

Génère une URL pré-signée pour accéder à l'objet OSS d'entrée.

Paramètres de la commande query

Paramètre

Obligatoire

Description

--vector-bucket-name

Oui

Le nom du bucket de vecteurs.

--index-name

Oui

Le nom de l'index de vecteurs.

--model-id

Oui

Spécifie l'ID du modèle DashScope utilisé pour générer les embeddings.

--text-value

Non

Le texte de la requête.

--text

Non

Le chemin d'accès à un fichier contenant le texte de la requête.

--image

Non

Le chemin d'accès à l'image à interroger.

--video

Non

L'URL de la vidéo à interroger.

--top-k

Non

Le nombre de résultats les plus similaires à renvoyer. Valeur par défaut : 5.

--filter

Non

Les critères de filtrage, spécifiés sous forme de chaîne JSON.

--return-distance

Non

Inclut la distance de similarité dans les résultats.

--return-metadata

Non

Inclut les métadonnées dans les résultats. Activé par défaut.

--dashscope-inference-params

Non

Spécifie les paramètres spécifiques au modèle à transmettre à DashScope au format JSON, par exemple '{"truncate": "END"}'.

--output

Non

Spécifie le format de sortie. Les valeurs valides sont json (par défaut) ou table.

Syntaxe de filtrage

Opérateur

Description

Exemple

$eq

Égal à

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

$ne

Différent de

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

$in/$nin

Dans ou hors d'une liste spécifiée

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

$and

ET logique

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

$or

OU logique

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

Références

Pour plus d'informations sur l'interface CLI OSS Vectors Embed, consultez le dépôt GitHub.