All Products
Search

This Product

    Object Storage Service:Manage vector data with OSS Vectors Embed CLI

    Document Center

    Object Storage Service:Manage vector data with OSS Vectors Embed CLI

    Last Updated:Mar 26, 2026

    The OSS Vectors Embed CLI is a command-line tool that lets you call Alibaba Cloud Model Studio vector models, vectorize OSS or local files, and write the vectors to an OSS Vector Bucket. It also supports multi-modal semantic search, which streamlines the development of applications like RAG knowledge bases and AI assistants. Key capabilities include:

    • Seamless integration: Integrates seamlessly with Alibaba Cloud Model Studio to vectorize data.

    • Multiple data sources: Supports data vectorization from multiple sources, including local files, OSS objects, third-party URLs, and text strings.

    • Flexible processing: Supports both single-file processing and batch vectorization of files within a specific path.

    • High customization: Lets you flexibly configure vector keys and scalar metadata.

    • Multimodal retrieval: Supports semantic similarity retrieval for text, images, and videos, empowering diverse business scenarios.

    Use the OSS Vectors Embed CLI to quickly set up a multimodal semantic search system in just a few simple commands and configure it with options such as batch write, custom vector key, and custom model parameters.

    The Alibaba Cloud OSS vectors embed CLI is in preview, and its parameters are subject to change.

    Step 1: Set up your environment

    Before you use the CLI, you need the following credentials:

    Configure credentials

    Configure your credentials as environment variables. The CLI automatically reads these variables, eliminating the need to provide them with each command.

    # 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>"
    Security tip: Do not hard-code credentials in scripts. Use environment variables instead.

    Install the OSS Vectors Embed CLI

    Python 3.9 or later is required.

    Option 1: Install with pip (recommended)

    pip install oss-vectors-embed-cli

    Option 2: Install in developer mode

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

    Verify the installation

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

    Create a vector bucket

    Before you can write vector data, you must create a vector bucket and configure a vector index:

    1. Create a vector bucket: Go to the vector bucket page in the OSS console and create one to store your vector data and indexes.

    2. Create a vector index: In your vector bucket, create a vector index and configure its vector dimension to match your embedding model.

    Important: The vector dimension of the vector index must match the output dimension of the embedding model. For example, if you use the text-embedding-v4 model (default: 1024 dimensions), you must also set the index's vector dimension to 1024.

    Step 2: Write vectors

    OSS vector buckets provide the PutVectors API to write vector data. The OSS Vectors Embed CLI encapsulates multiple API calls—reading the source file (GetObject), generating an embedding with Model Studio, and writing the vector data (PutVectors)—into a singleput command. Each file is processed into a single embedding. Automatic chunking for long documents is not currently supported.

    Write vectors from text files

    Use a text embedding model, such as text-embedding-v4, to generate embeddings from text. Supported input sources include text strings, OSS objects, and local text files.

    From an inline text string

    Generate an embedding from an inline text string and write it to a vector bucket:

    # Parameter descriptions:
# --account-id:         Your Alibaba Cloud ID.
# --vectors-region:     The region of the OSS vector bucket.
# --vector-bucket-name: The name of the OSS vector bucket.
# --index-name:         The 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"

    Sample command output (includes the vector key, bucket information, and metadata):

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

    Note: The CLI automatically adds source information fields, prefixed with OSSVECTORS-EMBED-SRC-*, to the metadata to trace the vector's origin.

    From a local text file

    Generate an embedding from a local file and write it to a vector bucket:

    # Parameter descriptions:
# --account-id:         Your Alibaba Cloud ID.
# --vectors-region:     The region of the OSS vector bucket.
# --vector-bucket-name: The name of the OSS vector bucket.
# --index-name:         The name of the OSS vector index.
# --model-id:           The embedding model to use.
# --text:               The 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>"

    Sample command output:

    {
  "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, to a voice assistant planning 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"
  }
}

    From an OSS object

    Generate an embedding from an object stored in OSS and write it to a vector bucket. Use the path format oss://bucket-name/object-key.

    # Parameter descriptions:
# --account-id:         Your Alibaba Cloud ID.
# --vectors-region:     The region of the OSS vector bucket.
# --vector-bucket-name: The name of the OSS vector bucket.
# --index-name:         The name of the OSS vector index.
# --model-id:           The embedding model to use.
# --region:             The region of the source bucket.
# --text:               The 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>"

    Note: Use the --region parameter to specify the region of the source OSS object.

    Sample command output:

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

    Write vectors from image files

    Use a multimodal embedding model, such as qwen2.5-vl-embedding, to generate embeddings from images and videos. Supported input sources for images include local files, OSS objects, and HTTP/HTTPS URLs.

    From a local image

    Generate an embedding from a local image file and write it to a vector bucket:

    # Parameter descriptions:
# --account-id:         Your Alibaba Cloud ID.
# --vectors-region:     The region of the OSS vector bucket.
# --vector-bucket-name: The name of the OSS vector bucket.
# --index-name:         The name of the OSS vector index.
# --model-id:           The embedding model to use.
# --image:              The 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>"

    Sample command output:

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

    From an OSS object

    Generate an embedding from an image file stored in OSS and write it to a vector bucket. Use the path format oss://bucket-name/object-key.

    # Parameter descriptions:
# --account-id:         Your Alibaba Cloud ID.
# --vectors-region:     The region of the OSS vector bucket.
# --vector-bucket-name: The name of the OSS vector bucket.
# --index-name:         The name of the OSS vector index.
# --model-id:           The embedding model to use.
# --region:             The region of the source bucket.
# --image:              The 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>"

    Sample command output:

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

    From an image URL

    Generate an embedding from an image URL and write it to a vector bucket:

    # Parameter descriptions:
# --account-id:         Your Alibaba Cloud ID.
# --vectors-region:     The region of the OSS vector bucket.
# --vector-bucket-name: The name of the OSS vector bucket.
# --index-name:         The name of the OSS vector index.
# --model-id:           The embedding model to use.
# --image:              The 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"

    Sample command output:

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

    Write vectors from video files

    Use a multimodal vector model (such as qwen2.5-vl-embedding) to process images and videos. Supported input sources for videos include OSS video files and HTTP/HTTPS URL files. Video processing extracts keyframes from the video and generates a separate embedding for each frame. Because each embedding requires a unique key, the --key and --filename-as-key parameters are not supported. The CLI automatically generates a unique sequential key for each frame.

    From an OSS object

    To process a video file in OSS, the CLI generates a presigned URL for the object, creates the embeddings, and writes them to the vector bucket:

    # Parameter descriptions:
# --account-id:         Your Alibaba Cloud ID.
# --vectors-region:     The region of the OSS vector bucket.
# --vector-bucket-name: The name of the OSS vector bucket.
# --index-name:         The name of the OSS vector index.
# --model-id:           The embedding model to use.
# --region:             The region of the source video.
# --video:              The OSS path of the source video.
# --presign-url:        Generates a presigned URL for the OSS object, which is required for private buckets.

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

    Sample command output:

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

    From a video URL

    Generate an embedding from a video URL and write it to a vector bucket:

    # Parameter descriptions:
# --account-id:         Your Alibaba Cloud ID.
# --vectors-region:     The region of the OSS vector bucket.
# --vector-bucket-name: The name of the OSS vector bucket.
# --index-name:         The name of the OSS vector index.
# --model-id:           The embedding model to use.
# --video:              The 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"

    Sample command output:

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

    Add scalar metadata

    You can add custom scalar metadata to a write command to enable vector and scalar hybrid search.

    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 vector and scalar hybrid search.

    User-defined metadata fields are merged with the system-generated fields. Sample command output:

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

    Step 3: Vector search

    OSS Vector Buckets provide the QueryVectors API to perform vector similarity searches. The OSS-Vectors-Embed_CLI provides the query command to perform a similarity search. This command first vectorizes the query content (text or an image) and then searches the vector index to find the most semantically similar vectors.

    Important: The embedding model that you use for queries must match the model that you used to index the data.

    Text similarity search

    Find semantically similar vectors using a text query. The--top-k parameter controls the number of results to return. The following command searches the my-index index for vectors most similar to "What is artificial intelligence".

    # --text-value: The query text.
# --top-k:      The number of nearest neighbors 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

    The sample output includes vector keys and metadata:

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

    Note: By default, the similarity distance is not returned. To include it, add the --return-distance parameter.

    Image similarity search

    Use an image query to find the most similar vectors, enabling use cases like image-to-image search.

    # --image: The query image.
# --top-k: The number of nearest neighbors 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

    The sample output includes vector keys and metadata:

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

    Hybrid search

    Use the --filter parameter to filter results by metadata. This narrows the search scope for more precise queries. The OSS-Vectors-Embed-CLI supports simple filtering with a single metadata condition and combined filtering with multiple conditions.

    Single-condition filtering

    Query for vectors where the category is technology:

    # --filter: Apply a metadata filter.
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

    Note: The --return-metadata parameter includes all metadata in the results, including both user-defined and CLI-generated fields.

    Sample output:

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

    Multi-condition filtering

    The OSS-Vectors-Embed-CLI uses the filter syntax to combine multiple filter conditions, such as AND and OR. The following example uses an AND condition.

    AND query: Matches all 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

    Sample output:

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

    To display search results in a table format, use the --output table parameter. This converts the default JSON output to a readable table, ideal for interactive exploration and debugging.

    # --output table: Specify 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

    Sample table output:

                                     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

    Note: The Distance column shows N/A because the --return-distance parameter was omitted. To include the distance in the results, add this parameter to the query.

    Advanced configurations

    Batch processing

    The CLI uses wildcards for batch processing files in a directory. This mode automatically sends parallel requests to improve throughput. The following example processes all files under a specified prefix in an OSS bucket.

    # --text "oss://bucket/path/*": Vectorizes and writes all files under the specified prefix in a batch.
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/*"

    Sample output:

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

    For batch processing, you can use the--max-workers parameter to control concurrency (the default is 4). Increasing this value improves throughput but consumes more API quota. An OSS vector bucket supports batch writing of up to 500 vectors per request, with a maximum of 5 concurrent requests.

    # --max-workers: Sets 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

    Sample output:

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

    Custom vector keys

    The CLI offers flexible ways to specify vector keys. You can use a custom string, the source filename, or add a prefix to each key.

    Custom key

    Use the--key parameter to set the vector key to a specific value:

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

    Sample output:

    {
 "key": "doc-001",    // The vector key is set to "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"
 }
}

    Source filename as key

    Use the--filename-as-key parameter to automatically use the source filename as the vector key:

    # Use the source 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

    Sample output:

    {
  "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, to a voice assistant planning 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"
  }
}

    Key prefix

    # --key-prefix: Adds 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/"

    Sample output:

    {
  "key": "project-a/doc-001",    // The prefix "project-a/" is added to the vector key.
  "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"
  }
}

    Custom model parameters

    Use the--dashscope-inference-params parameter to fine-tune the embedding model's behavior for different scenarios.

    Write with custom parameters

    When vectorizing data, you can specify parameters such as the output type and dimension:

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

    Sample output:

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

    Query with custom parameters

    When querying vectors, you can control behaviors such as the text truncation policy:

    # 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

    Sample output:

    {
  "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": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 10,
    "queryDimensions": 1024
  }
}

    Supported embedding models

    Text embedding models

    Model ID

    Default dimension

    Optional dimensions

    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

    —

    Multimodal embedding models

    Model ID

    Dimensions

    Input types

    qwen2.5-vl-embedding

    2048/1024/768/512

    Text, images, and video

    tongyi-embedding-vision-plus

    1152

    Text, images, and video

    tongyi-embedding-vision-flash

    768

    Text, images, and video

    multimodal-embedding-v1

    1024

    Text, image, and video

    Model selection guidance:

    • For text-only use cases, use text-embedding-v4.

    • For use cases that combine text and images, use qwen2.5-vl-embedding.

    • For high-speed applications, use tongyi-embedding-vision-flash.

    Parameters

    Global parameters

    Parameter

    Required

    Description

    --account-id

    Yes

    Your Alibaba Cloud account ID.

    --vectors-region

    Yes

    The region of the vector bucket, for example, cn-hangzhou.

    --vectors-endpoint

    No

    The access endpoint for the vector bucket.

    --debug

    No

    Enables debug mode.

    Put command parameters

    Parameter

    Required

    Description

    --vector-bucket-name

    Yes

    The name of the vector bucket.

    --index-name

    Yes

    The name of the vector index.

    --model-id

    Yes

    The ID of the DashScope model that generates vectors.

    --text-value

    No

    The text to process. You must specify only one of --text-value, --text, --image, or --video.

    --text

    No

    The path to a text file or an OSS object.

    --image

    No

    The path to an image file, an OSS object, or a URL.

    --video

    No

    The URL of the video.

    --key

    No

    A custom unique key for the vector.

    --key-prefix

    No

    Adds a prefix to an automatically generated or user-specified key.

    --filename-as-key

    No

    Uses the input filename as the vector key.

    --dashscope-inference-params

    No

    Passes model-specific parameters to DashScope in JSON format, for example, '{"dimension": "1024"}'.

    --metadata

    No

    The metadata for the vector, in JSON format.

    --max-workers

    No

    The maximum number of concurrent requests for batch processing. The default is 4.

    --batch-size

    No

    The number of vectors per batch write request. The value must be between 1 and 500. The default is 500.

    --output

    No

    Specifies the output format. Valid values are json (default) or table.

    --region

    No

    The region of the source OSS object. Required if the input is an OSS object.

    --presign-url

    No

    Enables access via a presigned URL when the input is an OSS object.

    Query command parameters

    Parameter

    Required

    Description

    --vector-bucket-name

    Yes

    The name of the vector bucket.

    --index-name

    Yes

    The name of the vector index.

    --model-id

    Yes

    The ID of the DashScope model that generates vectors.

    --text-value

    No

    The query text.

    --text

    No

    The path to a file that contains the query text.

    --image

    No

    The path to the image to query.

    --video

    No

    The URL of the video to query.

    --top-k

    No

    The number of nearest neighbors to return. The default is 5.

    --filter

    No

    The filter criteria, specified as a JSON string.

    --return-distance

    No

    Includes the similarity distance in the results.

    --return-metadata

    No

    Includes metadata in the results. Enabled by default.

    --dashscope-inference-params

    No

    Passes model-specific parameters to DashScope in JSON format, for example, '{"truncate": "END"}'.

    --output

    No

    Specifies the output format. Valid values are json (default) or table.

    Filter syntax

    Operator

    Description

    Example

    $eq

    Equals

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

    $ne

    Not equals

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

    $in/$nin

    In / Not in an array

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

    $and

    Logical AND

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

    $or

    Logical OR

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

    References

    For more information about the OSS Vectors Embed CLI, see the OSS Vectors Embed CLI on GitHub.