Ikhtisar Fungsi PenyematanCompatible with Milvus 2.6.x

Modul Function di Milvus memungkinkan Anda untuk mengubah data teks mentah menjadi penyematan vektor dengan secara otomatis memanggil penyedia layanan penyematan eksternal (seperti OpenAI, AWS Bedrock, Google Vertex AI, dll.). Dengan modul Function, Anda tidak perlu lagi berinteraksi secara manual dengan embedding API-Milvus menangani seluruh proses pengiriman permintaan ke penyedia, menerima embedding, dan menyimpannya dalam koleksi Anda. Untuk pencarian semantik, Anda hanya perlu menyediakan data kueri mentah, bukan vektor kueri. Milvus menghasilkan vektor kueri dengan model yang sama dengan yang Anda gunakan untuk penyematan, membandingkannya dengan vektor yang tersimpan, dan mengembalikan hasil yang paling relevan.

Batasan

• Setiap bidang input yang disematkan modul Function harus selalu berisi nilai; jika nilai null diberikan, modul akan melemparkan kesalahan.

• Modul Function hanya memproses bidang yang secara eksplisit didefinisikan dalam skema koleksi; modul ini tidak menghasilkan penyematan untuk bidang dinamis.

• Bidang input yang akan disematkan harus bertipe VARCHAR.

• Modul Function dapat menyematkan bidang input ke:

  • FLOAT_VECTOR

  • INT8_VECTOR

  Konversi ke BINARY_VECTOR, FLOAT16_VECTOR, atau BFLOAT16_VECTOR tidak didukung.

Penyedia layanan penyematan yang didukung

Penyedia	Model Umum	Jenis Penyematan	Metode Autentikasi
OpenAI	penyematan teks-3-*	FLOAT_VECTOR	Kunci API
Azure OpenAI	Berbasis penyebaran	FLOAT_VECTOR	Kunci API
DashScope	penyematan teks-v3	FLOAT_VECTOR	Kunci API
Batuan dasar	amazon.titan-embed-text-v2	FLOAT_VECTOR	Pasangan AK/SK
Vertex AI	penyematan-teks-005	FLOAT_VECTOR	Kredensial JSON akun layanan GCP
Voyage AI	voyage-3, voyage-lite-02	FLOAT_VECTOR / INT8_VECTOR	Kunci API
Cohere	embed-english-v3.0	FLOAT_VECTOR / INT8_VECTOR	Kunci API
SiliconFlow	BAAI/bge-besar-zh-v1.5	FLOAT_VECTOR	Kunci API
Memeluk Wajah	Semua model yang dilayani TEI	FLOAT_VECTOR	Kunci API opsional

Bagaimana cara kerjanya

Diagram berikut ini menunjukkan bagaimana Fungsi bekerja di Milvus.

1. Memasukkan teks: Pengguna memasukkan data mentah (misalnya dokumen) ke dalam Milvus.

2. Menghasilkan penyematan: Modul Function di dalam Milvus secara otomatis memanggil penyedia model yang telah dikonfigurasi untuk mengkonversi data mentah menjadi embedding vektor.

3. Menyimpan embeddings: Penyematan yang dihasilkan disimpan dalam bidang vektor yang didefinisikan secara eksplisit dalam koleksi Milvus.

4. Kueri teks: Pengguna mengirimkan kueri teks ke Milvus.

5. Pencarian semantik: Milvus secara internal mengubah kueri menjadi sematan vektor, melakukan pencarian kemiripan terhadap sematan yang tersimpan, dan mengambil hasil yang relevan.

6. Mengembalikan hasil: Milvus mengembalikan hasil pencocokan teratas ke aplikasi.

Ikhtisar Fungsi Penyematan

Mengonfigurasi kredensial

Sebelum menggunakan fungsi penyematan dengan Milvus, konfigurasikan kredensial layanan penyematan untuk akses Milvus.

Milvus memungkinkan Anda memberikan kredensial layanan penyematan dengan dua cara:

• Berkas konfigurasi (milvus.yaml):

  Contoh pada topik ini mendemonstrasikan penyiapan yang direkomendasikan menggunakan milvus.yaml.

• Variabel lingkungan:

  Untuk detail tentang cara mengonfigurasi kredensial melalui variabel lingkungan, lihat dokumentasi penyedia layanan penyematan (misalnya, OpenAI atau Azure OpenAI).

Diagram berikut ini menunjukkan proses konfigurasi kredensial melalui file konfigurasi Milvus (milvus.yaml) dan kemudian memanggil Fungsi dalam Milvus.

Konfigurasi Kredensial Melimpah

Langkah 1: Menambahkan kredensial ke file konfigurasi Milvus

Pada berkas milvus.yaml anda, edit blok credential dengan entri untuk setiap penyedia yang perlu anda akses:

# milvus.yaml credential store section
# This section defines all your authentication credentials for external embedding providers
# Each credential gets a unique name (e.g., aksk1, apikey1) that you'll reference elsewhere
credential:
  # For AWS Bedrock or services using access/secret key pairs
  # 'aksk1' is just an example name - you can choose any meaningful identifier
  aksk1:                       
    access_key_id: <YOUR_AK>      
    secret_access_key: <YOUR_SK>  
  
  # For OpenAI, Voyage AI, or other API key-based services
  # 'apikey1' is a custom name you choose to identify this credential  
  apikey1:                     
    apikey: <YOUR_API_KEY>        
  
  # For Google Vertex AI using service account credentials
  # 'gcp1' is an example name for your Google Cloud credentials
  gcp1:                        
    credential_json: <BASE64_OF_JSON>

Langkah 2: Konfigurasi pengaturan penyedia

Pada berkas konfigurasi yang sama (milvus.yaml), edit blok function untuk memberi tahu Milvus kunci mana yang akan digunakan untuk menyematkan panggilan layanan:

function:
  textEmbedding:
    providers:
      openai:                         # calls OpenAI
        credential: apikey1           # Reference to the credential label
        # url:                        # (optional) custom url

      bedrock:                        # calls AWS Bedrock
        credential: aksk1             # Reference to the credential label
        region: us-east-2

      vertexai:                       # calls Google Vertex AI
        credential: gcp1              # Reference to the credential label
        # url:                        # (optional) custom url

      tei:                            # Built-in Tiny Embedding model
        enable: true                  # Whether to enable TEI model service

Untuk informasi lebih lanjut tentang cara menerapkan konfigurasi Milvus, lihat Mengkonfigurasi Milvus dengan Cepat.

Menggunakan fungsi penyematan

Setelah kredensial dikonfigurasikan dalam berkas konfigurasi Milvus Anda, ikuti langkah-langkah berikut untuk mendefinisikan dan menggunakan fungsi penyematan.

Langkah 1: Mendefinisikan bidang skema

Untuk menggunakan fungsi penyematan, buatlah koleksi dengan skema tertentu. Skema ini harus menyertakan setidaknya tiga bidang yang diperlukan:

• Bidang utama yang secara unik mengidentifikasi setiap entitas dalam koleksi.

• Bidang skalar yang menyimpan data mentah yang akan disematkan.

• Bidang vektor yang dicadangkan untuk menyimpan penyematan vektor yang akan dihasilkan oleh fungsi untuk bidang skalar.

Contoh berikut ini mendefinisikan skema dengan satu bidang skalar "document" untuk menyimpan data tekstual dan satu bidang vektor "dense" untuk menyimpan embedding yang akan dihasilkan oleh modul Function. Ingatlah untuk mengatur dimensi vektor (dim) agar sesuai dengan keluaran dari model penyematan yang Anda pilih.

from pymilvus import MilvusClient, DataType, Function, FunctionType

# Initialize Milvus client
client = MilvusClient(
    uri="http://localhost:19530",
)

# Create a new schema for the collection
schema = client.create_schema()

# Add primary field "id"
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)

# Add scalar field "document" for storing textual data
schema.add_field("document", DataType.VARCHAR, max_length=9000)

# Add vector field "dense" for storing embeddings.
# IMPORTANT: Set dim to match the exact output dimension of the embedding model.
# For instance, OpenAI's text-embedding-3-small model outputs 1536-dimensional vectors.
# For dense vector, data type can be FLOAT_VECTOR or INT8_VECTOR
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

// java

// nodejs

// go

# restful

Langkah 2: Menambahkan fungsi penyematan ke skema

Modul Function di Milvus secara otomatis mengubah data mentah yang disimpan dalam bidang skalar menjadi penyematan dan menyimpannya ke dalam bidang vektor yang didefinisikan secara eksplisit.

Contoh di bawah ini menambahkan modul Function (openai_embedding) yang mengubah bidang skalar "document" menjadi embedding, menyimpan vektor yang dihasilkan dalam bidang vektor "dense" yang didefinisikan sebelumnya.

# Define embedding function (example: OpenAI provider)
text_embedding_function = Function(
    name="openai_embedding",                  # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING, # Type of embedding function
    input_field_names=["document"],           # Scalar field to embed
    output_field_names=["dense"],             # Vector field to store embeddings
    params={                                  # Provider-specific configuration (highest priority)
        "provider": "openai",                 # Embedding model provider
        "model_name": "text-embedding-3-small",     # Embedding model
        # "credential": "apikey1",            # Optional: Credential label
        # Optional parameters:
        # "dim": "1536",       # Optionally shorten the vector dimension
        # "user": "user123"    # Optional: identifier for API tracking
    }
)

# Add the embedding function to your schema
schema.add_function(text_embedding_function)

// java

// nodejs

// go

# restful

Parameter	Deskripsi	Nilai Contoh
name	Pengenal unik untuk fungsi penyematan di dalam Milvus.	"openai_embedding"
function_type	Jenis fungsi yang digunakan. Untuk penyematan teks, setel nilainya ke FunctionType.TEXTEMBEDDING. Catatan: Milvus menerima FunctionType.BM25 (untuk transformasi penyematan jarang) dan FunctionType.RERANK (untuk pemeringkatan) untuk parameter ini. Lihat Pencarian Teks Lengkap dan Gambaran Umum Pemeringkatan Peluruhan untuk detailnya.	FunctionType.TEXTEMBEDDING
input_field_names	Bidang skalar yang berisi data mentah yang akan disematkan. Saat ini, parameter ini hanya menerima satu nama bidang.	["document"]
output_field_names	Bidang vektor untuk menyimpan sematan yang dihasilkan. Saat ini, parameter ini hanya menerima satu nama bidang.	["dense"]
params	Kamus yang berisi konfigurasi penyematan. Catatan: Parameter dalam params bervariasi, tergantung pada penyedia model penyematan.	{...}
provider	Penyedia model penyematan.	"openai"
model_name	Menentukan model penyematan yang akan digunakan.	"text-embedding-3-small"
credential	Label kredensial yang ditentukan di bagian credential: tingkat atas dari milvus.yaml. Jika disediakan, Milvus mengambil pasangan kunci yang cocok atau token API dan menandatangani permintaan di sisi server. Ketika dihilangkan (None), Milvus kembali ke kredensial yang dikonfigurasikan secara eksplisit untuk penyedia model target di milvus.yaml. Jika label tidak diketahui atau kunci yang direferensikan tidak ada, panggilan akan gagal.	"apikey1"
dim	Jumlah dimensi untuk penyematan keluaran. Untuk model generasi ketiga OpenAI, Anda dapat mempersingkat vektor penuh untuk mengurangi biaya dan latensi tanpa kehilangan informasi semantik yang signifikan. Untuk informasi lebih lanjut, lihat posting blog pengumuman OpenAI. Catatan: Jika Anda memperpendek dimensi vektor, pastikan nilai dim yang ditentukan dalam metode add_field skema untuk bidang vektor sesuai dengan dimensi keluaran akhir fungsi penyematan Anda.	"1536"
user	Pengenal tingkat pengguna untuk melacak penggunaan API.	"user123"

Langkah 3: Konfigurasi indeks

Setelah mendefinisikan skema dengan bidang yang diperlukan dan fungsi bawaan, siapkan indeks untuk koleksi Anda. Untuk menyederhanakan proses ini, gunakan AUTOINDEX sebagai index_type, sebuah opsi yang memungkinkan Milvus untuk memilih dan mengonfigurasi jenis indeks yang paling sesuai berdasarkan struktur data Anda.

# Prepare index parameters
index_params = client.prepare_index_params()

# Add AUTOINDEX to automatically select optimal indexing method
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE" 
)

// java

// nodejs

// go

# restful

Langkah 4: Membuat koleksi

Sekarang buatlah koleksi menggunakan skema dan parameter indeks yang telah ditentukan.

# Create collection named "demo"
client.create_collection(
    collection_name='demo', 
    schema=schema, 
    index_params=index_params
)

// java

// nodejs

// go

# restful

Langkah 5: Masukkan data

Setelah menyiapkan koleksi dan indeks, Anda siap untuk memasukkan data mentah. Dalam proses ini, Anda hanya perlu menyediakan teks mentah. Modul Fungsi yang kita definisikan sebelumnya secara otomatis menghasilkan vektor jarang yang sesuai untuk setiap entri teks.

# Insert sample documents
client.insert('demo', [
    {'id': 1, 'document': 'Milvus simplifies semantic search through embeddings.'},
    {'id': 2, 'document': 'Vector embeddings convert text into searchable numeric data.'},
    {'id': 3, 'document': 'Semantic search helps users find relevant information quickly.'},
])

// java

// nodejs

// go

# restful

Langkah 6: Lakukan pencarian vektor

Setelah penyisipan data, lakukan pencarian semantik menggunakan teks kueri mentah. Milvus secara otomatis mengubah kueri Anda menjadi vektor penyisipan, mengambil dokumen yang relevan berdasarkan kemiripan, dan mengembalikan hasil yang paling cocok.

# Perform semantic search
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'], # Use text query rather than query vector
    anns_field='dense',   # Use the vector field that stores embeddings
    limit=1,
    output_fields=['document'],
)

print(results)

# Example output:
# data: ["[{'id': 1, 'distance': 0.8821347951889038, 'entity': {'document': 'Milvus simplifies semantic search through embeddings.'}}]"]

// java

// nodejs

// go

# restful

Untuk informasi lebih lanjut tentang operasi pencarian dan kueri, lihat Pencarian dan Kueri Vektor Dasar.

PERTANYAAN UMUM

Apa perbedaan antara mengonfigurasi kredensial di milvus.yaml vs variabel lingkungan?

Kedua metode ini dapat digunakan, tetapi menggunakan milvus.yaml adalah pendekatan yang direkomendasikan karena menyediakan manajemen kredensial terpusat dan penamaan kredensial yang konsisten di semua penyedia. Saat menggunakan variabel lingkungan, nama variabel bervariasi tergantung pada penyedia layanan penyematan, jadi rujuklah ke halaman khusus masing-masing penyedia untuk memahami nama variabel lingkungan spesifik yang diperlukan (misalnya, OpenAI atau Azure OpenAI).

Apa yang terjadi jika saya tidak menentukan parameter kredensial dalam definisi fungsi?

Milvus mengikuti urutan resolusi kredensial ini:

1. Pertama, mencari kredensial default yang dikonfigurasi untuk penyedia tersebut di file milvus.yaml
2. Jika tidak ada kredensial default yang ada di milvus.yaml, maka akan kembali ke variabel lingkungan (jika dikonfigurasi)
3. Jika kredensial milvus.yaml maupun variabel lingkungan tidak dikonfigurasi, Milvus akan melemparkan kesalahan

Bagaimana cara memverifikasi bahwa penyematan dibuat dengan benar?

Anda dapat memeriksanya dengan:

1. Menguji koleksi Anda setelah penyisipan untuk melihat apakah bidang vektor berisi data
2. Memeriksa apakah panjang bidang vektor sesuai dengan dimensi yang Anda harapkan
3. Melakukan pencarian kemiripan sederhana untuk memverifikasi penyematan menghasilkan hasil yang berarti

Ketika saya melakukan pencarian kemiripan, dapatkah saya menggunakan vektor kueri dan bukan teks mentah?

Ya, Anda dapat menggunakan vektor kueri yang telah dihitung sebelumnya, bukan teks mentah untuk pencarian kemiripan. Meskipun modul Fungsi secara otomatis mengubah kueri teks mentah menjadi sematan, Anda juga dapat secara langsung memberikan data vektor ke parameter data dalam operasi pencarian Anda. Catatan: Ukuran dimensi vektor kueri yang Anda berikan harus konsisten dengan ukuran dimensi sematan vektor yang dihasilkan oleh modul Function.

Contoh:

# Using raw text (Function module converts automatically)
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'],
    anns_field='dense',
    limit=1
)

# Using pre-computed query vector (must match stored vector dimensions)
query_vector = [0.1, 0.2, 0.3, ...]  # Must be same dimension as stored embeddings
results = client.search(
    collection_name='demo', 
    data=[query_vector],
    anns_field='dense',
    limit=1
)

// java

// nodejs

// go

# restful