Mengelola Sumber Daya File

Sumber daya berkas adalah referensi yang terdaftar di server ke berkas kamus eksternal yang digunakan oleh penganalisis teks pada saat proses. Pada Milvus 3.0, empat komponen penganalisis dapat memuat kamus mereka dari sumber daya file, bukan dari larik sebaris:

Komponen penganalisis	Parameter yang menerima sumber daya file
Jieba tokenizer	extra_dict_file
Penyaring berhenti	stop_words_file
Filter pengurai	word_list_file
Filter sinonim	synonyms_file

Sumber daya berkas memecahkan dua masalah praktis dengan larik kamus sebaris:

• Kamus yang asli berukuran besar. Kosakata Jieba bahasa Mandarin dapat terdiri dari puluhan ribu baris; tabel sinonim biasanya terdiri dari ribuan aturan. Memasukkannya ke dalam konfigurasi penganalisis tidak praktis.

• Kamus yang sama biasanya digunakan bersama di seluruh koleksi. Mendaftarkannya sekali, lalu merujuknya berdasarkan nama, membuat skema tetap kecil dan membuat pembaruan kamus menjadi satu operasi.

Jenis sumber daya berkas

Milvus mendukung dua jenis sumber daya berkas dengan tanggung jawab manajemen yang berbeda:

Jenis	Di mana berkas berada	Siapa yang mengelola berkas tersebut	Cocok
Jarak jauh	Di penyimpanan objek (MinIO / S3 / GCS / Azure) yang telah dikonfigurasi untuk digunakan oleh cluster Milvus Anda	Milvus, melalui API klien add_file_resource / remove_file_resource / list_file_resources	Direkomendasikan untuk sebagian besar penerapan.
Lokal	Pada jalur absolut yang sama pada sistem berkas lokal setiap komponen Milvus (DataNode, QueryNode, StreamingNode)	Anda - memasang berkas sendiri, misalnya melalui volume Kubernetes	Skenario open-source / self-hosted di mana Anda lebih suka mengelola berkas kamus di luar Milvus.

Sisa dari halaman ini akan membahas kedua jenis tersebut, dimulai dengan jenis remote yang lebih umum.

Prasyarat

• Untuk sumber daya berkas jarak jauh, penyebaran Milvus Anda harus dikonfigurasikan dengan penyimpanan objek. Sebagian besar deployment sudah melakukannya - periksa bagian minio: pada milvus.yaml Anda (atau nilai bagan Helm yang setara). Perhatikan nilai bucketName dan rootPath; Anda akan membutuhkannya saat mendaftarkan sumber daya berkas.

• Untuk sumber daya berkas Lokal, Anda harus dapat menempatkan berkas pada setiap pod/kontainer Milvus pada jalur absolut yang sama. Bagaimana Anda melakukannya tergantung pada penerapan Anda (bind mount, volume yang didukung ConfigMap, init kontainer, dll.).

Mendaftarkan sumber daya berkas jarak jauh

Mendaftarkan sumber daya berkas jarak jauh merupakan alur kerja tiga langkah: unggah berkas ke penyimpanan objek, daftarkan dengan Milvus dengan nama yang dipilih, lalu rujuk dari penganalisis mana pun yang membutuhkannya.

Langkah 1. Unggah file kamus ke penyimpanan objek

Gunakan perkakas Anda sendiri (mc, aws s3 cp, boto3, atau klien yang kompatibel dengan S3) untuk meletakkan berkas di dalam bucket yang telah dikonfigurasikan untuk digunakan oleh Milvus.

Misalnya, jika milvus.yaml berisi:

minio:
  bucketName: milvus-bucket
  rootPath: file

Mengunggah berkas bernama chinese_terms.txt dengan rootPath sebagai awalan akan menempatkan objek di s3://milvus-bucket/file/chinese_terms.txt.

Argumen path yang akan Anda berikan ke add_file_resource pada Langkah 2 adalah kunci objek lengkap, termasuk awalan rootPath - untuk contoh di atas, path="file/chinese_terms.txt". Jalur tanpa awalan (misalnya, hanya "chinese_terms.txt") akan ditolak dengan kesalahan file resource path not exist.

Langkah 2. Daftarkan berkas dengan add_file_resource

from pymilvus import MilvusClient

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

client.add_file_resource(
    name="chinese_terms",                # short, unique name you'll reference later
    path="file/chinese_terms.txt",       # full S3 object key, including the rootPath prefix
)

add_file_resource memvalidasi secara sinkron: pemanggilan kembali hanya setelah Milvus mengonfirmasi bahwa objek tersebut ada di path dalam penyimpanan objek yang telah dikonfigurasi. Jika objek tidak ada, pemanggilan akan memunculkan MilvusException(code=65535, "file resource path not exist") - unggah berkas terlebih dahulu, lalu coba lagi.

Pemanggilan ini tidak berhasil. Memanggil add_file_resource dua kali dengan name dan path yang sama tidak akan menghasilkan duplikat.

Langkah 3. Merujuk sumber daya file dari penganalisis

Di mana pun parameter penganalisis menerima referensi file (extra_dict_file, stop_words_file, word_list_file, synonyms_file), gunakan bentuk jarak jauh kanonik:

{
    "type": "remote",
    "resource_name": "chinese_terms",    # must match the name in add_file_resource
    "file_name": "chinese_terms.txt",    # filename only — Milvus uses this to identify the file inside the resource
}

Keempat parameter penganalisis menggunakan bentuk yang sama; hanya kunci penganalisis di sekelilingnya yang berbeda. Untuk contoh konkret per penganalisis, lihat Jieba tokenizer, Stop filter, Decompounder filter, dan Synonym filter.

Nama parameternya adalah resource_name dan file_name - bukan name dan file. Menggunakan name / file (atau "type": "resource" dan bukan "type": "remote") akan memunculkan MilvusException pada saat pembuatan penganalisis dengan pesan seperti resource name of remote file ... must be set.

Daftar sumber daya file

resources = client.list_file_resources()
for r in resources:
    print(r.name, r.path)
# chinese_terms file/chinese_terms.txt

list_file_resources() mengembalikan daftar objek FileResourceInfo, masing-masing dengan atribut .name dan .path. Cluster kosong mengembalikan []. Tidak ada per-sumber daya get; list_file_resources adalah satu-satunya API yang dapat dibaca.

Menghapus sumber daya berkas

client.remove_file_resource(name="chinese_terms")

remove_file_resource adalah idempoten: memanggilnya untuk nama yang tidak ada akan mengembalikan None tanpa memunculkan.

Sebelum menghapus sumber daya berkas, hapus atau ubah koleksi apa pun yang konfigurasi penganalisisnya mereferensikannya. Menyimpan sumber daya berkas hingga tidak ada koleksi yang bergantung padanya akan menghindari risiko pencarian penganalisis gagal setelah sumber daya tersebut hilang.

Gunakan sumber daya file lokal

Sumber daya berkas lokal menunjuk langsung ke jalur pada sistem berkas lokal setiap komponen Milvus. Tidak ada panggilan add_file_resource - Milvus tidak melacak sumber daya lokal. Anda menempatkan berkas pada jalur absolut yang sama pada setiap pod atau kontainer yang relevan, lalu merujuknya dengan jalur:

{
    "type": "local",
    "path": "/var/lib/milvus/dicts/chinese_terms.txt",
}

Sumber daya berkas lokal hanya berlaku dalam penerapan di mana Anda mengendalikan sistem berkas DataNode, QueryNode, dan StreamingNode - biasanya Milvus yang dihosting sendiri pada bare-metal atau pada kluster Kubernetes di mana Anda dapat menambahkan mount volume. File harus berada di jalur absolut yang sama persis pada setiap komponen; jika tidak, beberapa node akan gagal saat memuat penganalisis.

Berkas tersebut dibuka saat penganalisis pertama kali dibuat. Jika jalurnya tidak ada pada saat itu, pembuatan penganalisis akan gagal dengan MilvusException(code=2000, "IOError: No such file or directory").

Pertimbangan

• Ketersediaan di seluruh cluster tidak instan. Setelah add_file_resource kembali, Milvus menyinkronkan file tersebut ke setiap komponen yang membutuhkannya. Selama jendela singkat ini, koleksi yang mereferensikan sumber daya mungkin gagal dibuat pada node yang belum disinkronkan. Perbaikan yang umum dilakukan adalah dengan mencoba kembali panggilan create setelah beberapa detik.

• Hapus hanya jika tidak ada koleksi yang bergantung pada sumber daya. Buang atau ubah koleksi apa pun yang konfigurasi penganalisisnya mereferensikan sumber daya sebelum memanggil remove_file_resource, untuk menghindari pencarian penganalisis yang gagal menemukan berkas.

• Hanya metadata. list_file_resources() mengembalikan name dan path - tidak ada ukuran, checksum, waktu pengunggahan, atau metadata lainnya. Pantau versi kamus dengan konvensi penamaan Anda sendiri jika Anda membutuhkannya.