Object Storage Service:Kelola data vektor dengan OSS Vectors Embed CLI

Konfigurasi kredensial

Konfigurasikan kredensial Anda sebagai variabel lingkungan. CLI akan membaca variabel ini secara otomatis, sehingga Anda tidak perlu memasukkannya setiap kali menjalankan 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: Jangan hard-code kredensial di dalam skrip. Gunakan variabel lingkungan sebagai gantinya.

Instal OSS Vectors Embed CLI

Diperlukan Python 3.9 atau versi lebih baru.

Opsi 1: Instal dengan pip (disarankan)

pip install oss-vectors-embed-cli

Opsi 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

Sebelum dapat menulis data vektor, Anda harus membuat bucket vektor dan mengonfigurasi indeks vektor:

1. Buat bucket vektor: Buka halaman bucket vektor di konsol OSS dan buat satu untuk menyimpan data vektor dan indeks Anda.

2. Buat indeks vektor: Di dalam bucket vektor Anda, buat indeks vektor dan atur dimensi vektornya agar sesuai dengan model penyematan Anda.

Penting: Dimensi vektor pada indeks vektor harus sesuai dengan dimensi output dari model penyematan. Misalnya, jika Anda menggunakan model text-embedding-v4 (dimensi default: 1024), Anda juga harus mengatur dimensi vektor indeks menjadi 1024.

Tulis vektor dari file teks

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

Dari string teks inline

Hasilkan penyematan dari string teks inline dan tulis ke bucket vektor:

# Penjelasan parameter:
# --account-id:         ID Alibaba Cloud Anda.
# --vectors-region:     Wilayah bucket vektor OSS.
# --vector-bucket-name: Nama bucket vektor OSS.
# --index-name:         Nama indeks vektor OSS.
# --model-id:           Model penyematan 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 output perintah (termasuk kunci vektor, informasi bucket, dan 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"
  }
}

Catatan: CLI secara otomatis menambahkan bidang informasi sumber, dengan awalan OSSVECTORS-EMBED-SRC-*, ke metadata untuk melacak asal vektor.

Dari file teks lokal

Hasilkan penyematan dari file lokal dan tulis ke bucket vektor:

# Penjelasan parameter:
# --account-id:         ID Alibaba Cloud Anda.
# --vectors-region:     Wilayah bucket vektor OSS.
# --vector-bucket-name: Nama bucket vektor OSS.
# --index-name:         Nama indeks vektor OSS.
# --model-id:           Model penyematan yang digunakan.
# --text:               Path 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 output perintah:

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

Dari objek OSS

Hasilkan penyematan dari objek yang disimpan di OSS dan tulis ke bucket vektor. Gunakan format path oss://bucket-name/object-key.

# Penjelasan parameter:
# --account-id:         ID Alibaba Cloud Anda.
# --vectors-region:     Wilayah bucket vektor OSS.
# --vector-bucket-name: Nama bucket vektor OSS.
# --index-name:         Nama indeks vektor OSS.
# --model-id:           Model penyematan yang digunakan.
# --region:             Wilayah bucket sumber.
# --text:               Path OSS dari 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: Gunakan parameter --region untuk menentukan wilayah objek OSS sumber.

Contoh output perintah:

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

Tulis vektor dari file gambar

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

Dari gambar lokal

Hasilkan penyematan dari file gambar lokal dan tulis ke bucket vektor:

# Penjelasan parameter:
# --account-id:         ID Alibaba Cloud Anda.
# --vectors-region:     Wilayah bucket vektor OSS.
# --vector-bucket-name: Nama bucket vektor OSS.
# --index-name:         Nama indeks vektor OSS.
# --model-id:           Model penyematan yang digunakan.
# --image:              Path 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 output perintah:

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

Dari objek OSS

Hasilkan penyematan dari file gambar yang disimpan di OSS dan tulis ke bucket vektor. Gunakan format path oss://bucket-name/object-key.

# Penjelasan parameter:
# --account-id:         ID Alibaba Cloud Anda.
# --vectors-region:     Wilayah bucket vektor OSS.
# --vector-bucket-name: Nama bucket vektor OSS.
# --index-name:         Nama indeks vektor OSS.
# --model-id:           Model penyematan yang digunakan.
# --region:             Wilayah bucket sumber.
# --image:              Path OSS dari 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 output perintah:

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

Dari URL gambar

Hasilkan penyematan dari URL gambar dan tulis ke bucket vektor:

# Penjelasan parameter:
# --account-id:         ID Alibaba Cloud Anda.
# --vectors-region:     Wilayah bucket vektor OSS.
# --vector-bucket-name: Nama bucket vektor OSS.
# --index-name:         Nama indeks vektor OSS.
# --model-id:           Model penyematan 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 output perintah:

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

Tulis vektor dari file video

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

Dari objek OSS

Untuk memproses file video di OSS, CLI menghasilkan URL yang ditandatangani untuk objek tersebut, membuat penyematan, lalu menulisnya ke bucket vektor:

# Penjelasan parameter:
# --account-id:         ID Alibaba Cloud Anda.
# --vectors-region:     Wilayah bucket vektor OSS.
# --vector-bucket-name: Nama bucket vektor OSS.
# --index-name:         Nama indeks vektor OSS.
# --model-id:           Model penyematan yang digunakan.
# --region:             Wilayah video sumber.
# --video:              Path OSS dari video sumber.
# --presign-url:        Menghasilkan URL yang ditandatangani untuk objek OSS, yang diperlukan untuk bucket privat.

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 output perintah:

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

Dari URL video

Hasilkan penyematan dari URL video dan tulis ke bucket vektor:

# Penjelasan parameter:
# --account-id:         ID Alibaba Cloud Anda.
# --vectors-region:     Wilayah bucket vektor OSS.
# --vector-bucket-name: Nama bucket vektor OSS.
# --index-name:         Nama indeks vektor OSS.
# --model-id:           Model penyematan 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 output perintah:

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

Anda dapat menambahkan metadata skalar kustom ke perintah tulis untuk mengaktifkan pencarian hibrida vektor dan skalar.

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 pencarian hibrida vektor dan skalar.

Bidang metadata yang ditentukan pengguna digabungkan dengan bidang yang dihasilkan sistem. Contoh output perintah:

{
  "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 yang ditambahkan
    "version": "1.0",          // Metadata kustom yang ditambahkan
    "author": "admin",         // Metadata kustom yang ditambahkan
    "OSSVECTORS-EMBED-SRC-CONTENT": "Technical document content",
    "OSSVECTORS-EMBED-SRC-CONTENT-TYPE": "TEXT",
    "OSSVECTORS-EMBED-SRC-LOCATION": "direct_text_input"
  }
}

Pencarian kemiripan teks

Temukan vektor yang paling mirip secara semantik menggunakan kueri teks. Parameter --top-k mengontrol jumlah hasil yang dikembalikan. Perintah berikut mencari indeks my-index untuk vektor yang paling mirip dengan "What is artificial intelligence".

# --text-value: Teks kueri.
# --top-k:      Jumlah tetangga terdekat 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 mencakup 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 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
  }
}

Catatan: Secara default, jarak kemiripan tidak dikembalikan. Untuk menyertakannya, tambahkan parameter --return-distance.

Pencarian kemiripan gambar

Gunakan kueri gambar untuk menemukan vektor yang paling mirip, memungkinkan kasus penggunaan seperti pencarian gambar-ke-gambar.

# --image: Gambar kueri.
# --top-k: Jumlah tetangga terdekat 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 mencakup kunci vektor dan metadata:

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

Gunakan parameter --filter untuk memfilter hasil berdasarkan metadata. Ini mempersempit cakupan pencarian untuk kueri yang lebih tepat. OSS Vectors Embed CLI mendukung pemfilteran sederhana dengan satu kondisi metadata dan pemfilteran gabungan dengan beberapa kondisi.

Pemfilteran satu kondisi

Kueri vektor dengan category bernilai technology:

# --filter: Terapkan filter 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

Catatan: Parameter --return-metadata menyertakan semua metadata dalam hasil, termasuk bidang yang ditentukan pengguna dan yang dihasilkan 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 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
  }
}

Pemfilteran multi-kondisi

OSS Vectors Embed CLI menggunakan sintaks filter untuk menggabungkan beberapa kondisi filter, seperti AND dan OR. Contoh berikut menggunakan kondisi AND.

Kueri AND: Cocok dengan 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 mudah dibaca, ideal untuk eksplorasi interaktif dan debugging.

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

                                 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 parameter --return-distance tidak disertakan. Untuk menyertakan jarak dalam hasil, tambahkan parameter ini ke kueri.

Pemrosesan batch

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

# --text "oss://bucket/path/*": Melakukan vektorisasi dan menulis semua file di bawah awalan yang ditentukan dalam satu 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/*"

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

Kunci vektor kustom

CLI menyediakan cara fleksibel untuk menentukan kunci vektor. Anda dapat menggunakan string kustom, nama file sumber, atau menambahkan awalan ke setiap 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 diatur menjadi "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 sumber "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, 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: Menambahkan 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",    // Awalan "project-a/" ditambahkan ke kunci vektor.
  "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"
  }
}

Parameter model kustom

Gunakan parameter --dashscope-inference-params untuk menyesuaikan perilaku model penyematan sesuai skenario berbeda.

Tulis dengan parameter kustom

Saat melakukan vektorisasi data, Anda dapat menentukan parameter seperti tipe output dan dimensi:

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

Kueri dengan parameter kustom

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

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

Model penyematan teks

Model penyematan multimodal

Panduan pemilihan model:

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

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

• Untuk aplikasi berkecepatan tinggi, gunakan tongyi-embedding-vision-flash.

Parameter global

Parameter perintah Put

Parameter perintah Query

Sintaks filter