Object Storage Service:Manage vectors with OSS Vectors Embed CLI

Configure access credentials

Set your access credentials as environment variables. The CLI automatically reads these variables when it runs, so you can omit them from your commands.

# 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: Use environment variables instead of hard-coding credentials in scripts.

Install the OSS Vectors Embed CLI

Requires Python 3.9 or later.

Method 1: Install using pip (recommended)

pip install oss-vectors-embed-cli

Method 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

To write vector data, first create a vector bucket and configure an index:

1. Create a vector bucket: On the Vector Bucket page, create a bucket to store your vector data and indexes.

2. Create a vector index: In the new bucket, create an index and set its vector dimension to match your vector model's output dimension.

Important: The vector index dimension must match the output dimension of the vector model you use. For example, if you use the text-embedding-v4 model, which defaults to 1024 dimensions, the index dimension must also be set to 1024.

Generate embeddings from text files

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

Use a text string as input

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

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

Sample response:

{
  "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 OSSVECTORS-EMBED-SRC-* fields to the metadata to trace the source of the embedding.

Use a local text file as input

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

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

Sample response:

{
  "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 an OSS object as input

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

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

Note: You must use the --region parameter to specify the region of the source OSS object.

Sample response:

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

Generate embeddings from image files

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

Use a local image as input

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

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

Sample response:

{
  "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 an OSS object as input

Generate an embedding from an image stored in an OSS object and write it to your OSS vector bucket. The object path must be in the oss://bucket-name/object-key format.

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

Sample response:

{
  "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 an image URL as input

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

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

Sample response:

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

Generate embeddings from video files

Use a multimodal embedding model, such as qwen2.5-vl-embedding, to process videos. Supported input sources are OSS video files and HTTP/HTTPS URLs. When processing a video, the CLI extracts keyframes 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.

Use an OSS object as input

Generate embeddings from an OSS video file (which involves creating a presigned URL for access) and write them to your OSS vector bucket:

# 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

Sample response:

{
  "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 a video URL as input

Generate embeddings from a video at a URL and write them to your OSS vector bucket:

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

Sample response:

{
  "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 during writes

You can attach custom scalar metadata when writing an embedding. This data can then be used in filtered queries.

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

User-defined metadata fields are merged with the automatically generated system fields. Sample response:

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

Text similarity search

You can query for semantically similar vectors based on a text input. The --top-k parameter controls the number of results to return. Run the following command to search the my-index vector index for vectors that are semantically similar to "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

Sample output (includes the vector key and metadata):

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

Note: The similarity distance is not returned by default. To include it in the results, add the --return-distance parameter.

Image similarity search

You can find the most similar vectors based on an image query. This supports use cases like image-to-image search.

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

Sample output (includes the vector key and metadata):

{
  "results": [
    {
      "Key": "11dcf66b-708a-4707-8bd4-8656bead19da",          // A search result, containing 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
  }
}

Metadata-filtered search

You can use the --filter parameter to perform metadata post-filtering. This narrows the search scope and provides more precise results. The oss-vectors-embed-cli supports simple filtering based on a single metadata field and combined filtering using multiple conditions.

Simple filtering

Query for vectors where the category is 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

Note: The --return-metadata parameter returns the complete metadata in the results, including both user-defined fields and those automatically added by the CLI.

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

Combined filtering

The oss-vectors-embed-cli lets you combine multiple filter conditions, such as AND and OR, based on the filter syntax. The following example shows 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 output the search results in a table format, use the --output table parameter. This converts the default JSON output to a table, which is easier for manual review, interactive exploration, and debugging.

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

Sample 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 command does not include the --return-distance parameter. Add this parameter to display the distance values.

Batch processing

The CLI supports batch processing for all files in a directory using a wildcard. In batch mode, the CLI automatically sends parallel requests to improve throughput. The following example uses a wildcard to batch process all files under a specific prefix in an OSS bucket.

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

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

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

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

Customize vector keys

The CLI provides flexible options for specifying the vector key. You can set a custom string, use the original filename, or add a prefix to all keys.

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

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

# 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

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

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

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

Customize model parameters

Use the --dashscope-inference-params parameter to fine-tune the vector model for different business scenarios.

Write with custom parameters

When vectorizing data, specify parameters such as output type and 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"}'

Sample response:

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

# 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

Sample response:

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

Text embedding models

Multimodal embedding models

Model selection recommendations:

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

• For mixed text-and-image use cases, use qwen2.5-vl-embedding.

• For low-latency use cases, consider tongyi-embedding-vision-flash.

Global parameters

put command parameters

query command parameters

Filter syntax