Object Storage Service：使用OSS Vectors Embed CLI工具寫入和檢索向量資料

配置訪問憑證

將訪問憑證配置為環境變數。CLI 在執行時會自動讀取這些變數，無需在命令中重複提供。

# 阿里雲賬戶 AccessKey 
export OSS_ACCESS_KEY_ID="<your-access-key-id>"
export OSS_ACCESS_KEY_SECRET="<your-access-key-secret>"

# 百鍊 API Key
export DASHSCOPE_API_KEY="<your-dashscope-api-key>"

安全提示：請勿在指令碼中寫入程式碼憑證，建議使用環境變數。

安裝OSS Vectors Embed CLI

支援 Python 3.9 或更高版本。

方式一：pip 安裝（推薦）

pip install oss-vectors-embed-cli

方式二：開發模式安裝

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

驗證安裝

oss-vectors-embed --version
# 輸出: oss-vectors-embed, version 0.1.0

建立向量Bucket

寫入向量資料之前，需要建立向量 Bucket 並配置索引：

1. 建立向量 Bucket：在向量Bucket頁面建立向量Bucket，用於儲存向量資料和索引。

2. 建立向量索引：在已建立的向量 Bucket 中建立索引，配置與向量模型匹配的向量維度。

重要：向量索引的維度必須與所用向量模型輸出維度一致。例如，使用 text-embedding-v4 模型（預設 1024 維）時，索引維度也應設為 1024。

寫入文字檔的向量

使用文本向量模型（如 text-embedding-v4）處理文本。輸入源支援文本字串、OSS 對象或本地文字檔。

直接輸入文本

通過命令列直接輸入文本產生向量並將其寫入到向量 Bucket：

# 參數說明：
# --account-id:         阿里雲 ID
# --vectors-region:     OSS 向量 Bucket 所在地區
# --vector-bucket-name: OSS 向量 Bucket 名稱
# --index-name:         OSS 向量 Index 名稱
# --model-id:           使用的向量模型
# --text-value:         直接輸入文本

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 "人工智慧正在改變我們的生活"

命令返回樣本（包含向量鍵、Bucket 資訊和中繼資料）：

{
  "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": "人工智慧正在改變我們的生活",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

說明：CLI 會自動在中繼資料中添加源資訊欄位（OSSVECTORS-EMBED-SRC-*），用於追溯向量來源。

讀取本地文字檔

寫入本地檔案以產生向量並將其寫入到向量 Bucket：

# 參數說明：
# --account-id:         阿里雲 ID
# --vectors-region:     OSS 向量 Bucket 所在地區
# --vector-bucket-name: OSS 向量 Bucket 名稱
# --index-name:         OSS 向量 Index 名稱
# --model-id:           使用的向量模型
# --text:               本地檔案路徑

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

命令返回樣本：

{
  "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": "人工智慧正在改變我們的生活。從清晨被智能鬧鐘根據睡眠周期輕柔喚醒，到通勤途中語音助手為我們規劃最優路線；從家中智能音箱播放個人化新聞摘要，到工作時AI工具自動產生報告、翻譯文檔、最佳化流程——AI已悄然融入日常的每個角落。",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "./documents/article.txt"
  }
}

讀取 OSS 對象

直接寫入儲存在OSS中的對象（路徑格式：oss://bucket-name/object-key）並將其寫入到向量 Bucket：

# 參數說明：
# --account-id:         阿里雲 ID
# --vectors-region:     OSS 向量 Bucket 所在地區
# --vector-bucket-name: OSS 向量 Bucket 名稱
# --index-name:         OSS 向量 Index 名稱
# --model-id:           使用的向量模型
# --region:             源檔案 Bucket 所在地區
# --text:               源檔案 OSS 路徑

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

注意：需使用 --region 參數指定源 OSS 對象所在的地區。

命令返回樣本：

{
  "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 a example file.",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "oss://source-bucket/documents/file.txt"
  }
}

寫入圖片檔案的向量

使用多模態向量模型（如 qwen2.5-vl-embedding）處理圖片和視頻。輸入源支援本地檔案、OSS 對象或 HTTP/HTTPS URL。

讀取本地圖片

讀取本地圖片檔案產生向量並將其寫入向量 Bucket：

# 參數說明：
# --account-id:         阿里雲 ID
# --vectors-region:     OSS 向量 Bucket 所在地區
# --vector-bucket-name: OSS 向量 Bucket 名稱
# --index-name:         OSS 向量 Index 名稱
# --model-id:           使用的向量模型
# --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 "<./images/photo.jpg>"

命令返回樣本：

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

讀取 OSS 對象

讀取儲存在OSS圖片檔案（路徑格式：oss://bucket-name/object-key）產生向量並將其寫入向量 Bucket：

# 參數說明：
# --account-id:         阿里雲 ID
# --vectors-region:     OSS 向量 Bucket 所在地區
# --vector-bucket-name: OSS 向量 Bucket 名稱
# --index-name:         OSS 向量 Index 名稱
# --model-id:           使用的向量模型
# --region:             源檔案 Bucket 所在地區
# --image:              源圖片 OSS 路徑

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

命令返回樣本：

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

讀取圖片URL

對 URL 檔案產生向量並將其寫入向量 Bucket：

# 參數說明：
# --account-id:         阿里雲 ID
# --vectors-region:     OSS 向量 Bucket 所在地區
# --vector-bucket-name: OSS 向量 Bucket 名稱
# --index-name:         OSS 向量 Index 名稱
# --model-id:           使用的向量模型
# --image:              圖片 URL 地址

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"

命令返回樣本：

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

寫入視頻檔案的向量

使用多模態向量模型（如 qwen2.5-vl-embedding）處理圖片和視頻。輸入源支援 OSS 視頻檔案、 HTTP/HTTPS URL 檔案。視頻處理會提取視頻中的主要畫面格，並為每一幀產生一個獨立的向量。每個向量都需要唯一的鍵，因此不支援使用 --key 或 --filename-as-key 參數。CLI 會為每一幀自動產生唯一的序列鍵。

讀取OSS對象

對 OSS 視頻檔案產生預簽名 URL，完成向量化並寫入向量 Bucket：

# 參數說明：
# --account-id:         阿里雲 ID
# --vectors-region:     OSS 向量 Bucket 所在地區
# --vector-bucket-name: OSS 向量 Bucket 名稱
# --index-name:         OSS 向量 Index 名稱
# --model-id:           使用的向量模型
# --region:             源視頻 所在地區
# --video:              源視頻 OSS 路徑
# --presign-url:        對 OSS 地址產生簽名 URL 後再訪問（適用於私人 Bucket 等情境）

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

命令返回樣本：

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

讀取視頻URL

對 URL 檔案產生向量並將其寫入向量 Bucket：

# 參數說明：
# --account-id:         阿里雲 ID
# --vectors-region:     OSS 向量 Bucket 所在地區
# --vector-bucket-name: OSS 向量 Bucket 名稱
# --index-name:         OSS 向量 Index 名稱
# --model-id:           使用的向量模型
# --video:              視頻 URL 地址

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"

命令返回樣本：

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

寫入時添加標量中繼資料

在向量寫入的命令中添加自訂標量中繼資料，可用於向量和標量混合檢索。

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 "技術文檔內容" \
  --metadata '{"category": "technology", "version": "1.0", "author": "admin"}' #添加自訂標量中繼資料，使用者向量和標量混合檢索

使用者自訂的中繼資料欄位將與系統自動添加的欄位合并儲存。命令返回樣本：

{
  "key": "c0ed4d9d-5301-49a5-82b7-eaf9d02b04a9",
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "category": "technology",  //已添加的自訂中繼資料
    "version": "1.0",          //已添加的自訂中繼資料
    "author": "admin",         //已添加的自訂中繼資料
    "OSSVECTORS-EMBED-SRC-CONTENT": "技術文檔內容",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

文本向量相似性檢索

根據文字查詢語義相似的向量，其中--top-k 參數控制返回的結果數量。執行以下命令，在 my-index 索引中搜尋與“什麼是人工智慧”語義最相似的向量。

# --text-value: Query 檢索文本
# --top-k:      檢索返回最相似的向量結果數量

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 "什麼是人工智慧" \
  --top-k 100

查詢輸出樣本（包含向量鍵和中繼資料）：

{
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSSVECTORS-EMBED-SRC-CONTENT": "人工智慧正在改變我們的生活",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 100,
    "queryDimensions": 1024
  }
}

說明：預設不返回相似性距離。如需擷取，添加 --return-distance 參數。

圖片向量相似性檢索

根據圖片來檢索最相似的向量資料，以實現“以圖搜圖”（尋找與映像匹配的圖片）等應用情境。

# --image:  Query 檢索圖片
# --top-k:  檢索返回最相似的向量結果數量

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                                    

查詢輸出樣本（包含向量鍵和中繼資料）：

{
  "results": [
    {
      "Key": "11dcf66b-708a-4707-8bd4-8656bead19da",          //檢索返回的向量結果，返迴向量 Key-Value 和標量中繼資料
      "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
  }
}

向量和標量混合檢索

可以使用 --filter 參數來進行標量中繼資料後過濾，進而縮小查詢範圍，實現更精確的搜尋。OSS-Vectors-Embed-CLI 命令列工具支援根據單一標量中繼資料進行簡單過濾，也可以根據多個條件進行組合過濾。

單條件簡單過濾

查詢 category 為 technology 的向量：

# --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 "技術文檔" \
  --filter '{"category": {"$eq": "technology"}}' \
  --top-k 20 \
  --return-metadata

說明：--return-metadata 參數用於在結果中返回完整的中繼資料（包括使用者自訂和 CLI 自動添加的欄位）。

查詢輸出樣本：

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

多條件組合過濾

OSS-Vectors-Embed-CLI 命令列工具支援基於過濾文法組合多個過濾條件查詢，如 AND、OR 等，以下以 AND 條件為例。

AND 查詢：匹配所有條件。

# AND: 兩個條件都必須匹配
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 參考" \
  --filter '{"$and": [{"category": "documentation"}, {"version": "3.0"}]}' \
  --top-k 5

查詢輸出樣本：

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

若希望使用以表格形式輸出檢索結果，可使用 --output table 參數可將預設的 JSON 輸出轉換為表格格式，更便於人工閱讀、互動式探索和調試。

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

表格輸出樣本：

                                 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

注意：Distance 列顯示 N/A 表示查詢時未指定返回距離值。如需顯示，請在命令中添加 --return-distance 參數。

批量處理

CLI 支援使用萬用字元對整個目錄的檔案進行批量處理。在批量模式下，CLI 會自動並行發起請求以提高處理效率。以下樣本使用萬用字元批量處理 OSS 儲存桶中指定首碼下的所有檔案。

# --text "oss://bucket/path/*" 僅對該 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： 設定並發
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"
  ]
}

自訂向量鍵

CLI 工具支援靈活指定向量索引值，可將其設定為特定自訂字串，或直接使用原始檔案名作為向量鍵，同時支援為向量鍵添加統一首碼。

# 自定向量 Key 值為 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 "文檔內容" \
  --key "doc-001" 

{
 "key": "doc-001",    //向量 Key 值為 “doc-001”
 "bucket": "my-test-2",
 "index": "test1",
 "model": "text-embedding-v4",
 "contentType": "text",
 "embeddingDimensions": 1024,
 "metadata": {
   "OSSVECTORS-EMBED-SRC-CONTENT": "文檔內容",
   "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}

# 將原始檔案 Key 值 “article.txt”設定為向量 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": "人工智慧正在改變我們的生活。從清晨被智能鬧鐘根據睡眠周期輕柔喚醒，到通勤途中語音助手為我們規劃最優路線；從家中智能音箱播放個人化新聞摘要，到工作時AI工具自動產生報告、翻譯文檔、最佳化流程——AI已悄然融入日常的每個角落。",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "article.txt"
  }
}

# key-prefix：添加向量 Key 值的 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-value "文檔內容" \
  --key "doc-001" \
  --key-prefix "project-a/"

{
  "key": "project-a/doc-001",    //向量 Key 值添加了“project-a/”的 Prefix
  "bucket": "my-vector-bucket",
  "index": "my-index",
  "model": "text-embedding-v4",
  "contentType": "text",
  "embeddingDimensions": 1024,
  "metadata": {
    "OSSVECTORS-EMBED-SRC-CONTENT": "文檔內容",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

自訂模型參數

通過 --dashscope-inference-params 參數可以精細控制向量模型的行為，以滿足不同業務情境的需求。

使用自訂模型參數寫入

在向量化資料時，可以指定輸出類型和維度等參數：

# dashscope-inference-params '{"output_type": "dense", "dimension": "1024"}'自訂模型的輸出類型和向量維度
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 "技術文檔內容" \
  --dashscope-inference-params '{"output_type": "dense", "dimension": "1024"}'

命令返回樣本：

{
 "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": "文檔內容",
   "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
   "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
 }
}

使用自訂模型參數檢索

檢索向量時，可以控制文本截斷策略等行為：

# --dashscope-inference-params '{"truncate": "END"}' 設定文本截斷策略
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 "技術文檔" \
  --dashscope-inference-params '{"truncate": "END"}' \
  --top-k 10
  --return-distance

命令返回樣本：

{
  "results": [
    {
      "Key": "3d8935dd-6395-4c9c-a501-df902846ec80",
      "metadata": {
        "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
        "OSSVECTORS-EMBED-SRC-CONTENT": "技術文檔",
        "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
      }
    },
    ...
  ],
  "summary": {
    "queryType": "text",
    "model": "text-embedding-v4",
    "index": "my-index",
    "resultsFound": 10,
    "queryDimensions": 1024
  }
}

文本向量模型

多模態向量模型

模型選擇建議：

• 純文字情境：推薦使用 text-embedding-v4

• 圖文混合情境：推薦使用 qwen2.5-vl-embedding

• 追求速度：可選用 tongyi-embedding-vision-flash

全域參數

put 命令參數

query 命令參數

過濾文法