Object Storage Service:Kelola vektor dengan OSS Vectors Embed CLI

Konfigurasikan kredensial akses

Tetapkan kredensial akses Anda sebagai variabel lingkungan. CLI akan membaca variabel ini secara otomatis saat dijalankan, sehingga Anda tidak perlu memasukkannya dalam perintah.

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

# Kunci API Model Studio
export DASHSCOPE_API_KEY="<your-dashscope-api-key>"

Tips Keamanan: Gunakan variabel lingkungan alih-alih menyematkan kredensial secara langsung dalam skrip.

Instal OSS Vectors Embed CLI

Memerlukan Python 3.9 atau versi lebih baru.

Metode 1: Instal menggunakan pip (disarankan)

pip install oss-vectors-embed-cli

Metode 2: Instal dalam mode developer

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

Verifikasi instalasi

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

Buat bucket vektor

Untuk menulis data vektor, pertama-tama buat bucket vektor dan konfigurasikan indeks:

1. Buat bucket vektor: Pada halaman Vector Bucket, buat bucket untuk menyimpan data vektor dan indeks Anda.

2. Buat indeks vektor: Di dalam bucket baru tersebut, buat indeks dan atur dimensi vektornya agar sesuai dengan dimensi output model vektor yang Anda gunakan.

Penting: Dimensi indeks vektor harus sesuai dengan dimensi output model vektor yang Anda gunakan. Misalnya, jika Anda menggunakan model text-embedding-v4 yang memiliki dimensi default 1024, maka dimensi indeks juga harus diatur menjadi 1024.

Hasilkan embedding dari file teks

Gunakan model text embedding, seperti text-embedding-v4, untuk memproses teks. Sumber input yang didukung mencakup string teks, objek OSS, dan file teks lokal.

Gunakan string teks sebagai input

Hasilkan embedding dari string teks inline dan tulis ke bucket vektor OSS Anda:

# Deskripsi parameter:
# --account-id:         ID akun Alibaba Cloud
# --vectors-region:     Wilayah bucket vektor OSS
# --vector-bucket-name: Nama bucket vektor OSS
# --index-name:         Nama indeks vektor OSS
# --model-id:           Model embedding yang digunakan
# --text-value:         String teks input

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"

Contoh respons:

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

Catatan: CLI secara otomatis menambahkan bidang OSSVECTORS-EMBED-SRC-* ke metadata untuk melacak sumber embedding.

Gunakan file teks lokal sebagai input

Hasilkan embedding dari file lokal dan tulis ke bucket vektor OSS Anda:

# Deskripsi parameter:
# --account-id:         ID akun Alibaba Cloud
# --vectors-region:     Wilayah bucket vektor OSS
# --vector-bucket-name: Nama bucket vektor OSS
# --index-name:         Nama indeks vektor OSS
# --model-id:           Model embedding yang digunakan
# --text:               Jalur ke file lokal

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

Contoh respons:

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

Gunakan objek OSS sebagai input

Hasilkan embedding dari objek yang disimpan di OSS dan tulis ke bucket vektor OSS Anda. Jalur objek harus dalam format oss://bucket-name/object-key.

# Deskripsi parameter:
# --account-id:         ID akun Alibaba Cloud
# --vectors-region:     Wilayah bucket vektor OSS
# --vector-bucket-name: Nama bucket vektor OSS
# --index-name:         Nama indeks vektor OSS
# --model-id:           Model embedding yang digunakan
# --region:             Wilayah bucket objek sumber
# --text:               Jalur OSS file sumber

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

Catatan: Anda harus menggunakan parameter --region untuk menentukan wilayah objek OSS sumber.

Contoh respons:

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

Hasilkan embedding dari file gambar

Gunakan model embedding multimodal, seperti qwen2.5-vl-embedding, untuk memproses gambar dan video. Sumber input yang didukung mencakup file lokal, objek OSS, dan URL HTTP/HTTPS.

Gunakan gambar lokal sebagai input

Hasilkan embedding dari file gambar lokal dan tulis ke bucket vektor OSS Anda:

# Deskripsi parameter:
# --account-id:         ID akun Alibaba Cloud
# --vectors-region:     Wilayah bucket vektor OSS
# --vector-bucket-name: Nama bucket vektor OSS
# --index-name:         Nama indeks vektor OSS
# --model-id:           Model embedding yang digunakan
# --image:              Jalur ke file gambar lokal

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

Contoh respons:

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

Gunakan objek OSS sebagai input

Hasilkan embedding dari gambar yang disimpan dalam objek OSS dan tulis ke bucket vektor OSS Anda. Jalur objek harus dalam format oss://bucket-name/object-key.

# Deskripsi parameter:
# --account-id:         ID akun Alibaba Cloud
# --vectors-region:     Wilayah bucket vektor OSS
# --vector-bucket-name: Nama bucket vektor OSS
# --index-name:         Nama indeks vektor OSS
# --model-id:           Model embedding yang digunakan
# --region:             Wilayah bucket objek sumber
# --image:              Jalur OSS gambar sumber

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

Contoh respons:

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

Gunakan URL gambar sebagai input

Hasilkan embedding dari gambar di URL dan tulis ke bucket vektor OSS Anda:

# Deskripsi parameter:
# --account-id:         ID akun Alibaba Cloud
# --vectors-region:     Wilayah bucket vektor OSS
# --vector-bucket-name: Nama bucket vektor OSS
# --index-name:         Nama indeks vektor OSS
# --model-id:           Model embedding yang digunakan
# --image:              URL gambar

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"

Contoh respons:

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

Hasilkan embedding dari file video

Gunakan model embedding multimodal, seperti qwen2.5-vl-embedding, untuk memproses video. Sumber input yang didukung adalah file video OSS dan URL HTTP/HTTPS. Saat memproses video, CLI mengekstraksi keyframe dan menghasilkan embedding terpisah untuk setiap frame. Karena setiap embedding memerlukan kunci unik, parameter --key dan --filename-as-key tidak didukung. CLI secara otomatis menghasilkan kunci unik berurutan untuk setiap frame.

Gunakan objek OSS sebagai input

Hasilkan embedding dari file video OSS (yang melibatkan pembuatan URL yang ditandatangani untuk akses) dan tulis ke bucket vektor OSS Anda:

# Deskripsi parameter:
# --account-id:         ID akun Alibaba Cloud
# --vectors-region:     Wilayah bucket vektor OSS
# --vector-bucket-name: Nama bucket vektor OSS
# --index-name:         Nama indeks vektor OSS
# --model-id:           Model embedding yang digunakan
# --region:             Wilayah bucket video sumber
# --video:              Jalur OSS video sumber
# --presign-url:        Menghasilkan URL yang ditandatangani untuk jalur OSS guna memberikan akses (untuk bucket privat dan skenario serupa).

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

Contoh respons:

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

Gunakan URL video sebagai input

Hasilkan embedding dari video di URL dan tulis ke bucket vektor OSS Anda:

# Deskripsi parameter:
# --account-id:         ID akun Alibaba Cloud
# --vectors-region:     Wilayah bucket vektor OSS
# --vector-bucket-name: Nama bucket vektor OSS
# --index-name:         Nama indeks vektor OSS
# --model-id:           Model embedding yang digunakan
# --video:              URL 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"

Contoh respons:

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

Tambahkan metadata skalar saat menulis

Anda dapat menyambungkan metadata skalar kustom saat menulis embedding. Data ini kemudian dapat digunakan dalam kueri terfilter.

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"}' # Tambahkan metadata skalar kustom untuk kueri terfilter

Bidang metadata yang ditentukan pengguna digabungkan dengan bidang sistem yang dihasilkan secara otomatis. Contoh respons:

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

Pencarian kemiripan teks

Anda dapat mencari vektor yang mirip secara semantik berdasarkan input teks. Parameter --top-k mengontrol jumlah hasil yang dikembalikan. Jalankan perintah berikut untuk mencari indeks vektor my-index guna menemukan vektor yang paling mirip secara semantik dengan "What is artificial intelligence".

# --text-value: Teks kueri.
# --top-k:      Jumlah vektor paling mirip yang dikembalikan.

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

Contoh output (termasuk kunci vektor dan 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
  }
}

Catatan: Jarak kemiripan tidak dikembalikan secara default. Untuk menyertakannya dalam hasil, tambahkan parameter --return-distance.

Pencarian kemiripan gambar

Anda dapat menemukan vektor paling mirip berdasarkan kueri gambar. Ini mendukung kasus penggunaan seperti pencarian gambar-ke-gambar.

# --image:  Gambar kueri.
# --top-k:  Jumlah vektor paling mirip yang dikembalikan.

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                                    

Contoh output (termasuk kunci vektor dan metadata):

{
  "results": [
    {
      "Key": "11dcf66b-708a-4707-8bd4-8656bead19da",          // Hasil pencarian, berisi kunci vektor dan 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
  }
}

Pencarian dengan filter metadata

Anda dapat menggunakan parameter --filter untuk melakukan post-filtering berdasarkan metadata. Ini mempersempit cakupan pencarian dan memberikan hasil yang lebih tepat. oss-vectors-embed-cli mendukung filtering sederhana berdasarkan satu bidang metadata dan filtering gabungan menggunakan beberapa kondisi.

Filtering sederhana

Cari vektor yang memiliki nilai category sebesar technology:

# --filter: Melakukan filtering berdasarkan metadata skalar.
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

Catatan: Parameter --return-metadata mengembalikan metadata lengkap dalam hasil, termasuk bidang yang ditentukan pengguna dan yang ditambahkan secara otomatis oleh CLI.

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

Filtering gabungan

oss-vectors-embed-cli memungkinkan Anda menggabungkan beberapa kondisi filter, seperti AND dan OR, berdasarkan sintaks filter. Contoh berikut menunjukkan kondisi AND.

Kueri AND: Mencocokkan semua kondisi.

# AND: Kedua kondisi harus cocok.
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

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

Untuk menampilkan hasil pencarian dalam format tabel, gunakan parameter --output table. Ini mengubah output JSON default menjadi tabel, yang lebih mudah untuk tinjauan manual, eksplorasi interaktif, dan debugging.

# --output table: Menentukan format output sebagai tabel.
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

Contoh 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

Catatan: Kolom Distance menampilkan N/A karena perintah tidak menyertakan parameter --return-distance. Tambahkan parameter ini untuk menampilkan nilai jarak.

Pemrosesan batch

CLI mendukung pemrosesan batch untuk semua file dalam direktori menggunakan wildcard. Dalam mode batch, CLI secara otomatis mengirim permintaan paralel untuk meningkatkan throughput. Contoh berikut menggunakan wildcard untuk memproses batch semua file di bawah awalan tertentu dalam bucket OSS.

# Gunakan --text "oss://bucket/path/*" untuk melakukan vektorisasi batch dan menulis hasil vektor untuk semua file di bawah awalan yang ditentukan.
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: Atur tingkat konkurensi.
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"
  ]
}

Menyesuaikan kunci vektor

CLI menyediakan opsi fleksibel untuk menentukan kunci vektor. Anda dapat mengatur string kustom, menggunakan nama file asli, atau menambahkan awalan ke semua kunci.

# Atur kunci vektor menjadi "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",    // Kunci vektor adalah "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"
 }
}

# Gunakan nama file "article.txt" sebagai kunci vektor.
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: Tambahkan awalan ke kunci vektor.
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",    // Kunci vektor diberi awalan "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"
  }
}

Kustomisasi parameter model

Gunakan parameter --dashscope-inference-params untuk menyesuaikan model vektor bagi berbagai skenario bisnis.

Tulis dengan parameter kustom

Saat melakukan vektorisasi data, tentukan parameter seperti tipe output dan dimensi:

# Gunakan --dashscope-inference-params '{"output_type": "dense", "dimension": "1024"}' untuk menyesuaikan tipe output dan dimensi vektor model.
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"}'

Contoh respons:

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

Kueri dengan parameter kustom

Saat melakukan kueri vektor, Anda dapat mengontrol perilaku seperti kebijakan pemotongan teks:

# Gunakan --dashscope-inference-params '{"truncate": "END"}' untuk mengatur kebijakan pemotongan teks.
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

Contoh respons:

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

Model text embedding

Model embedding multimodal

Rekomendasi pemilihan model:

• Untuk kasus penggunaan teks saja, gunakan text-embedding-v4.

• Untuk kasus penggunaan campuran teks dan gambar, gunakan qwen2.5-vl-embedding.

• Untuk kasus penggunaan latensi rendah, pertimbangkan tongyi-embedding-vision-flash.

Parameter global

Parameter perintah put

Parameter perintah query

Sintaks filter