Hugging FaceCompatible with Milvus v2.6.20+

Penggunaan model embedding Hugging Face biasanya mengharuskan aplikasi Anda untuk mengelola kredensial, memanggil model secara terpisah, dan menghasilkan embedding secara konsisten untuk data yang dimasukkan dan kueri pencarian. Dengan Fungsi Embedding Teks, Milvus memanggil Penyedia Inferensi Hugging Face yang dihosting untuk mengubah teks mentah menjadi vektor selama proses penyisipan dan pencarian.

Integrasi ini menggunakan router Hugging Face yang dihosting. Untuk menghubungkan Milvus ke layanan Text Embeddings Inference (TEI) yang diimplementasikan secara terpisah, lihat Hugging Face TEI.

Batasan

• Kolom keluaran Fungsi harus menggunakan tipe data ` FLOAT_VECTOR `. Embedding Hugging Face di Milvus tidak mendukung kolom keluaran ` INT8_VECTOR`, ` BINARY_VECTOR`, ` FLOAT16_VECTOR`, atau ` BFLOAT16_VECTOR `.
• Dimensi bidang keluaran Fungsi harus sesuai dengan dimensi keluaran model yang dipilih.

Cara kerjanya

Alur kerja embedding teks Hugging Face

Alur kerja ini memiliki tiga tahap:

1. Kirim teks mentah. Aplikasi Anda menyediakan teks mentah dalam permintaan penyisipan atau pencarian.
2. Menghasilkan embedding. Fungsi Text Embedding mengirimkan teks melalui hf-inference ke pipa Hugging Face feature-extraction. Fungsi ini menggunakan model_name untuk memilih model dan dapat meneruskan opsi inferensi yang didukung seperti normalisasi dan pemotongan.
3. Gunakan embedding. Hugging Face mengembalikan satu embedding bilangan floating-point per teks masukan. Selama proses penyisipan, Milvus menyimpan vektor tersebut di bidang keluaran Fungsi. Selama proses pencarian, Milvus menggunakan vektor tersebut sebagai vektor kueri.

Konfigurasi Fungsi yang sama menangani penyisipan dan pencarian, sehingga model dan parameter inferensi tetap konsisten di kedua operasi tersebut.

Sebelum Anda mulai

Sebelum menggunakan embedding teks Hugging Face yang dihosting, pastikan Anda memiliki:

• Milvus 2.6.20 atau yang lebih baru dalam lini rilis 2.6.
• PyMilvus 2.6.16 atau yang lebih baru.
• Token Akses Pengguna Hugging Face yang dapat memanggil Penyedia Inferensi.
• Model yang saat ini disediakan oleh hf-inference untuk feature-extraction tugas tersebut.

Contoh-contoh ini menggunakan sentence-transformers/all-MiniLM-L6-v2, yang menghasilkan embedding berdimensi 384. Model ini hanya digunakan untuk mendemonstrasikan konfigurasi dan bukan merupakan rekomendasi atau sertifikasi dari Milvus.

Konfigurasikan kredensial

Milvus memerlukan Token Akses Pengguna Hugging Face untuk memanggil router yang dihosting. Anda dapat mengonfigurasi token tersebut di milvus.yaml atau melalui variabel lingkungan.

Urutan prioritas kredensial adalah:

Function credential label -> provider credential label in milvus.yaml -> environment variable

Opsi 1: Berkas konfigurasi

Tentukan token di bawah bagian tingkat atas credential pada milvus.yaml, lalu arahkan penyedia embedding Hugging Face ke label kredensial tersebut:

# milvus.yaml
credential:
  huggingface_apikey:
    apikey: <YOUR_HUGGING_FACE_TOKEN>

function:
  textEmbedding:
    providers:
      huggingface:
        credential: huggingface_apikey
        # url: https://router.huggingface.co

Anda juga dapat mengatur ` credential ` di parameter Fungsi. Nilainya harus berupa label yang didefinisikan di bagian tingkat atas ` credential `, bukan token itu sendiri. Label kredensial tingkat Fungsi memiliki prioritas lebih tinggi daripada label tingkat penyedia.

Opsi 2: Variabel lingkungan

Jika baik konfigurasi Fungsi maupun penyedia tidak menentukan label kredensial, Milvus akan membaca token dari ` MILVUS_HUGGINGFACE_API_KEY`.

Untuk Docker Compose, atur variabel tersebut di layanan Milvus standalone:

# docker-compose.yaml
standalone:
  environment:
    MILVUS_HUGGINGFACE_API_KEY: <YOUR_HUGGING_FACE_TOKEN>

Untuk detail tentang penerapan pengaturan Docker Compose, lihat Konfigurasi Milvus dengan Docker Compose.

Gunakan embedding teks Hugging Face

Langkah 1: Buat koleksi dengan Fungsi Embedding Teks

Buat skema dengan bidang utama, bidang masukan " VARCHAR ", dan bidang keluaran " FLOAT_VECTOR ". Dimensi keluaran harus sesuai dengan model yang dipilih.

from pymilvus import DataType, Function, FunctionType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

collection_name = "hugging_face_embedding_demo"
schema = client.create_schema()

schema.add_field(
    field_name="id",
    datatype=DataType.INT64,
    is_primary=True,
    auto_id=False,
)
schema.add_field(
    field_name="document",
    datatype=DataType.VARCHAR,
    max_length=9000,
)
schema.add_field(
    field_name="dense",
    datatype=DataType.FLOAT_VECTOR,
    dim=384,
)

Tentukan Fungsi " TEXTEMBEDDING " yang menulis embedding dari " document " ke " dense":

text_embedding_function = Function(
    name="hugging_face_embedding",
    input_field_names=["document"],
    output_field_names=["dense"],
    function_type=FunctionType.TEXTEMBEDDING,
    params={
        "provider": "huggingface",
        "model_name": "sentence-transformers/all-MiniLM-L6-v2",
        "hf_provider": "hf-inference",
        "credential": "huggingface_apikey",
        "normalize": "true",
        "truncate": "true",
        "max_client_batch_size": 128,
    },
)

schema.add_function(text_embedding_function)

Jika Anda hanya menggunakan kredensial tingkat penyedia atau variabel lingkungan, abaikan " credential " dari parameter Fungsi.

Konfigurasikan indeks untuk bidang keluaran, lalu buat koleksi:

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE",
)

client.create_collection(
    collection_name=collection_name,
    schema=schema,
    index_params=index_params,
)

Tabel berikut menjelaskan parameter Fungsi khusus Hugging Face:

Parameter	Wajib?	Deskripsi
provider	Ya	Penyedia model embedding. Tetapkan nilai ini ke huggingface.
model_name	Ya	ID model Hugging Face untuk model yang disajikan melalui hf-inference untuk tugas feature-extraction.
hf_provider	Tidak	Rute Penyedia Inferensi Hugging Face. Nilai default dan satu-satunya yang didukung di Milvus 2.6.20 adalah hf-inference.
credential	Tidak	Label kredensial yang didefinisikan di bagian tingkat atas credential dari milvus.yaml. Nilai ini bukanlah token itu sendiri.
normalize	Tidak	Apakah Hugging Face harus mengembalikan embedding yang dinormalisasi. Nilai yang didukung adalah true dan false. Jika diabaikan, Milvus tidak akan menetapkan opsi ini dalam permintaan.
prompt_name	Tidak	Nama prompt yang didefinisikan dalam konfigurasi Sentence Transformers pada model yang dipilih.
truncate	Tidak	Apakah Hugging Face harus memotong input yang melebihi panjang yang didukung oleh model. Nilai yang didukung adalah true dan false.
truncation_direction	Tidak	Arah pemotongan input oleh Hugging Face. Nilai yang didukung adalah left dan right.
max_client_batch_size	Tidak	Jumlah maksimum teks masukan yang dikirim dalam satu permintaan Hugging Face. Nilai defaultnya adalah 128, dan nilainya harus lebih besar dari 0.

Langkah 2: Masukkan teks mentah

Masukkan teks tanpa menyertakan vektor. Milvus memanggil Hugging Face dan menulis embedding yang dihasilkan ke dense.

client.insert(
    collection_name=collection_name,
    data=[
        {
            "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.",
        },
    ],
)

Langkah 3: Pencarian dengan teks mentah

Lakukan pencarian dengan kueri teks. Milvus menerapkan konfigurasi Fungsi yang sama untuk membuat vektor kueri sebelum menjalankan pencarian vektor.

results = client.search(
    collection_name=collection_name,
    data=["How does Milvus handle semantic search?"],
    anns_field="dense",
    limit=3,
    output_fields=["document"],
    consistency_level="Strong",
)

print(results)

Hasilnya berisi dokumen-dokumen yang paling relevan dengan teks kueri, diurutkan berdasarkan kesamaan kosinus.

Pemecahan Masalah

Model tidak tersedia untuk ekstraksi fitur

Buka halaman model di Hugging Face dan periksa bagian " Inference Providers ". Pastikan " hf-inference " menyediakan model untuk " feature-extraction". Jika tidak, pilih model lain dan perbarui dimensi bidang vektor jika diperlukan.

Dimensi vektor yang dikembalikan tidak sesuai dengan bidang

Periksa dimensi keluaran model dan bandingkan dengan dim pada bidang Keluaran Fungsi. Milvus menolak respons yang dimensi vektornya berbeda dari dimensi bidang FLOAT_VECTOR.

Milvus melaporkan kredensial Hugging Face yang hilang

Pastikan label kredensial Fungsi ada di bagian credential tingkat atas, bahwa label tingkat penyedia valid, atau bahwa MILVUS_HUGGINGFACE_API_KEY ada di lingkungan layanan Milvus.

Langkah selanjutnya

• Untuk konsep umum Function dan perilaku penyisipan/pencarian, lihat Ikhtisar Fungsi Embedding.
• Untuk melakukan peringkat ulang kandidat pencarian vektor dengan skor kesamaan kalimat Hugging Face yang dihosting, lihat Hugging Face Ranker.