Azure OpenAICompatible with Milvus 2.6.x

Topik ini menjelaskan cara mengonfigurasi dan menggunakan fungsi-fungsi penyematan Azure OpenAI di Milvus.

Memilih model penyematan

Milvus mendukung semua model penyematan yang disediakan oleh Azure OpenAI. Di bawah ini adalah model-model embedding Azure OpenAI yang tersedia saat ini untuk referensi cepat:

Model	Dimensi	Token Maks	Deskripsi
penyematan-teks-3-kecil	Standar: 1.536 (dapat dipotong ke ukuran dimensi di bawah 1536)	8,191	Ideal untuk pencarian semantik yang sensitif terhadap biaya dan dapat diskalakan-menawarkan kinerja yang kuat dengan harga yang lebih rendah.
penyematan teks-3-besar	Standar: 3.072 (dapat dipotong ke ukuran dimensi di bawah 3072)	8,191	Terbaik untuk aplikasi yang menuntut akurasi pengambilan yang lebih baik dan representasi semantik yang lebih kaya.
penyematan teks-ada-002	Diperbaiki: 1.536 (tidak mendukung pemotongan)	8,191	Model generasi sebelumnya yang cocok untuk pipeline lama atau skenario yang membutuhkan kompatibilitas ke belakang.

Model penyematan generasi ketiga(text-embedding-3) mendukung pengurangan ukuran penyematan melalui parameter dim. Biasanya embedding yang lebih besar lebih mahal dari perspektif komputasi, memori, dan penyimpanan. Kemampuan untuk menyesuaikan jumlah dimensi memungkinkan kontrol yang lebih besar atas biaya dan kinerja secara keseluruhan. Untuk detail lebih lanjut tentang setiap model, lihat Penyematan.

Mengonfigurasi kredensial

Milvus harus mengetahui kunci API Azure OpenAI Anda sebelum dapat meminta penyematan. Milvus menyediakan dua metode untuk mengonfigurasi kredensial:

• File konfigurasi (disarankan): Simpan kunci API di milvus.yaml sehingga setiap restart dan node mengambilnya secara otomatis.

• Variabel lingkungan: Menyuntikkan kunci pada waktu penerapan-ideal untuk Docker Compose.

Pilih salah satu dari dua metode di bawah ini-file konfigurasi lebih mudah dikelola pada bare-metal dan VM, sedangkan rute env-var sesuai dengan alur kerja kontainer.

Opsi 1: Berkas konfigurasi (disarankan & prioritas lebih tinggi)

Simpan kunci API Anda di milvus.yaml; Milvus membacanya pada saat startup dan mengesampingkan variabel lingkungan apa pun untuk penyedia yang sama.

1. **Deklarasikan kunci Anda di bawah credential:

   Anda dapat mendaftarkan satu atau banyak kunci API-beri label yang Anda ciptakan dan akan direferensikan nanti.

   # milvus.yaml
   credential:
     apikey_dev:            # dev environment
       apikey: <YOUR_DEV_KEY>
     apikey_prod:           # production environment
       apikey: <YOUR_PROD_KEY>    
   

   Menempatkan kunci API di sini akan membuatnya tetap ada di seluruh proses restart dan memungkinkan Anda mengganti kunci hanya dengan mengubah label.

2. Beri tahu Milvus kunci mana yang akan digunakan untuk panggilan Azure OpenAI

   Di file yang sama, arahkan penyedia Azure OpenAI ke label yang Anda inginkan untuk digunakan.

   function:
     textEmbedding:
       providers:
         azure_openai:
           credential: apikey_dev      # ← choose any label you defined above
           resource_name:  # Your azure openai resource name
           # url: # Your azure openai embedding url
   

   Ini akan mengikat kunci tertentu untuk setiap permintaan yang dikirimkan Milvus ke titik akhir penyematan Azure OpenAI.

Opsi 2: Variabel lingkungan

Gunakan metode ini ketika Anda menjalankan Milvus dengan Docker Compose dan lebih memilih untuk menyimpan rahasia dari berkas dan gambar.

Milvus akan kembali ke variabel lingkungan hanya jika tidak ada kunci untuk penyedia yang ditemukan di milvus.yaml.

Variabel	Diperlukan	Deskripsi
MILVUSAI_AZURE_OPENAI_API_KEY	Ya	Membuat kunci Azure OpenAI tersedia di dalam setiap kontainer Milvus (diabaikan jika kunci untuk Azure OpenAI ada di milvus.yaml )
MILVUSAI_AZURE_OPENAI_RESOURCE_NAME	Ya	Nama sumber daya Azure OpenAI Anda seperti yang ditetapkan saat Anda membuat sumber daya layanan Azure OpenAI.

Dalam berkas docker-compose.yaml Anda, atur variabel lingkungan.

# docker-compose.yaml (standalone service section)
standalone:
  # ... other configurations ...
  environment:
    # ... other environment variables ...
    # Set the environment variable pointing to the Azure OpenAI API key inside the container
    MILVUSAI_AZURE_OPENAI_API_KEY: <MILVUSAI_AZURE_OPENAI_API_KEY>
    MILVUSAI_AZURE_OPENAI_RESOURCE_NAME: <MILVUSAI_AZURE_OPENAI_RESOURCE_NAME>

Blok environment: hanya menyuntikkan kunci ke dalam kontainer Milvus, membiarkan OS host Anda tidak tersentuh. Untuk detailnya, lihat Mengkonfigurasi Milvus dengan Docker Compose.

Menggunakan fungsi penyematan

Setelah kredensial dikonfigurasi, ikuti langkah-langkah berikut untuk mendefinisikan dan menggunakan fungsi penyematan.

Langkah 1: Mendefinisikan bidang skema

Untuk menggunakan fungsi penyematan, buat 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 output 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.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

Langkah 2: Menambahkan fungsi penyematan ke skema

Setelah Anda mendefinisikan fungsi penyematan Anda, tambahkan ke skema koleksi Anda. Ini menginstruksikan Milvus untuk menggunakan fungsi penyematan yang ditentukan untuk memproses dan menyimpan penyematan dari data teks Anda.

# Define embedding function specifically for Azure OpenAI provider
text_embedding_function = Function(
    name="azopenai",                                # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING,       # Indicates a text embedding function
    input_field_names=["document"],                 # Scalar field(s) containing text data to embed
    output_field_names=["dense"],                   # Vector field(s) for storing embeddings
    params={                                        # Provider-specific embedding parameters
        "provider": "azure_openai",                 # Embedding provider name (must be "azure_openai")
        "model_name": "zilliz-text-embedding-3-small",      # Model should be set to the deployment name you chose when you deployed the embedding model
        # Optional parameters (only specify if necessary):
        # "url": "https://{resource_name}.openai.azure.com/" # Optional: Your Azure OpenAI service endpoint
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "dim": "1536",                            # Optional: Shorten the output vector dimension
        # "user": "user123",                        # Optional: identifier for API tracking
    }
)

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

Langkah selanjutnya

Setelah mengonfigurasi fungsi penyematan, lihat Ikhtisar Fungsi untuk panduan tambahan mengenai konfigurasi indeks, contoh penyisipan data, dan operasi pencarian semantik.