# Jalankan Inferensi di server Inference adalah proses menggunakan model terlatih untuk membuat prediksi pada data baru. Karena proses ini dapat membutuhkan banyak komputasi, menjalankannya pada layanan khusus atau eksternal dapat menjadi opsi yang menarik. Perpustakaan `huggingface_hub` menyediakan antarmuka terpadu untuk menjalankan inference di berbagai layanan untuk model yang dihosting di Hugging Face Hub: 1. [Inference Providers](https://huggingface.co/docs/inference-providers/index): akses yang terpadu dan efisien ke ratusan model machine learning, didukung oleh mitra inferensi serverless kami. Pendekatan baru ini dibangun di atas Serverless Inference API kami sebelumnya, menawarkan lebih banyak model, kinerja yang lebih baik, dan keandalan yang lebih tinggi berkat penyedia kelas dunia. Lihat [dokumentasi](https://huggingface.co/docs/inference-providers/index#partners) untuk daftar penyedia yang didukung. 2. [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index): produk untuk dengan mudah mendeploy model ke produksi. Inferensi dijalankan oleh Hugging Face di infrastruktur khusus yang sepenuhnya dikelola pada penyedia cloud pilihan Anda. 3. Endpoint lokal: Anda juga dapat menjalankan inferensi dengan server inferensi lokal seperti [llama.cpp](https://github.com/ggerganov/llama.cpp), [Ollama](https://ollama.com/), [vLLM](https://github.com/vllm-project/vllm), [LiteLLM](https://docs.litellm.ai/docs/simple_proxy), atau [Text Generation Inference (TGI)](https://github.com/huggingface/text-generation-inference) dengan menghubungkan klien ke endpoint lokal ini. > [!TIP] > [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) adalah klien Python yang melakukan panggilan HTTP ke API kami. Jika Anda ingin melakukan panggilan HTTP secara langsung menggunakan alat pilihan Anda (curl, postman, ...), silakan merujuk ke dokumentasi [Inference Providers](https://huggingface.co/docs/inference-providers/index) atau halaman dokumentasi [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). > > Untuk pengembangan web, [klien JS](https://huggingface.co/docs/huggingface.js/inference/README) telah dirilis. Jika Anda tertarik dengan pengembangan game, Anda bisa melihat [proyek C#](https://github.com/huggingface/unity-api) kami. ## Memulai Mari kita mulai dengan tugas teks-ke-gambar: ```python >>> from huggingface_hub import InferenceClient # Example with an external provider (e.g. replicate) >>> replicate_client = InferenceClient( provider="replicate", api_key="my_replicate_api_key", ) >>> replicate_image = replicate_client.text_to_image( "A flying car crossing a futuristic cityscape.", model="black-forest-labs/FLUX.1-schnell", ) >>> replicate_image.save("flying_car.png") ``` Pada contoh di atas, kami menginisialisasi [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) dengan penyedia pihak ketiga, [Replicate](https://replicate.com/). Saat menggunakan penyedia, Anda harus menentukan model yang ingin digunakan. id model harus berupa id model di Hugging Face Hub, bukan id model dari penyedia pihak ketiga. Dalam contoh kami, kami menghasilkan gambar dari prompt teks. Nilai yang dikembalikan adalah objek `PIL.Image` yang dapat disimpan ke file. Untuk detail lebih lanjut, lihat dokumentasi [text_to_image()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_image). Sekarang kita akan melihat contoh penggunaan API [chat_completion()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion). Tugas ini menggunakan LLM untuk menghasilkan respons dari daftar pesan: ```python >>> from huggingface_hub import InferenceClient >>> messages = [ { "role": "user", "content": "What is the capital of France?", } ] >>> client = InferenceClient( provider="together", model="meta-llama/Meta-Llama-3-8B-Instruct", api_key="my_together_api_key", ) >>> client.chat_completion(messages, max_tokens=100) ChatCompletionOutput( choices=[ ChatCompletionOutputComplete( finish_reason="eos_token", index=0, message=ChatCompletionOutputMessage( role="assistant", content="The capital of France is Paris.", name=None, tool_calls=None ), logprobs=None, ) ], created=1719907176, id="", model="meta-llama/Meta-Llama-3-8B-Instruct", object="text_completion", system_fingerprint="2.0.4-sha-f426a33", usage=ChatCompletionOutputUsage(completion_tokens=8, prompt_tokens=17, total_tokens=25), ) ``` Pada contoh di atas, kami menggunakan penyedia pihak ketiga ([Together AI](https://www.together.ai/)) dan menentukan model yang ingin digunakan (`"meta-llama/Meta-Llama-3-8B-Instruct"`). Kemudian, kami memberikan daftar pesan untuk diselesaikan (di sini, satu pertanyaan) dan meneruskan parameter tambahan ke API (`max_token=100`). Outputnya adalah objek `ChatCompletionOutput` yang mengikuti spesifikasi OpenAI. Konten yang dihasilkan dapat diakses dengan `output.choices[0].message.content`. Untuk detail lebih lanjut, lihat dokumentasi [chat_completion()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion). > [!WARNING] > API dirancang agar sederhana. Tidak semua parameter dan opsi tersedia atau dijelaskan untuk pengguna akhir. Lihat [halaman ini](https://huggingface.co/docs/api-inference/detailed_parameters) jika Anda tertarik mempelajari lebih lanjut tentang semua parameter yang tersedia untuk setiap tugas. ### Menggunakan penyedia tertentu Jika Anda ingin menggunakan penyedia tertentu, Anda dapat menentukannya saat menginisialisasi klien. Nilai defaultnya adalah "auto" yang akan memilih penyedia pertama yang tersedia untuk model tersebut, diurutkan berdasarkan urutan pengguna di https://hf.co/settings/inference-providers. Lihat bagian [Penyedia dan tugas yang didukung](#supported-providers-and-tasks) untuk daftar penyedia yang didukung. ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(provider="replicate", api_key="my_replicate_api_key") ``` ### Menggunakan model tertentu Bagaimana jika Anda ingin menggunakan model tertentu? Anda dapat menentukannya sebagai parameter atau langsung di level instance: ```python >>> from huggingface_hub import InferenceClient # Initialize client for a specific model >>> client = InferenceClient(provider="together", model="meta-llama/Llama-3.1-8B-Instruct") >>> client.text_to_image(...) # Or use a generic client but pass your model as an argument >>> client = InferenceClient(provider="together") >>> client.text_to_image(..., model="meta-llama/Llama-3.1-8B-Instruct") ``` > [!TIP] > Saat menggunakan penyedia "hf-inference", setiap tugas dilengkapi dengan model yang direkomendasikan dari 1 juta+ model yang tersedia di Hub. Namun, rekomendasi ini dapat berubah seiring waktu, sehingga sebaiknya Anda secara eksplisit mengatur model setelah memutuskan model mana yang akan digunakan. Untuk penyedia pihak ketiga, Anda harus selalu menentukan model yang kompatibel dengan penyedia tersebut. > > Kunjungi halaman [Models](https://huggingface.co/models?inference=warm) di Hub untuk menjelajahi model yang tersedia melalui Inference Providers. ### Menggunakan Inference Endpoints Contoh yang kita lihat di atas menggunakan penyedia inferensi. Meskipun ini terbukti sangat berguna untuk membuat prototipe dan menguji sesuatu dengan cepat. Begitu Anda siap untuk mendeploy model Anda ke produksi, Anda perlu menggunakan infrastruktur khusus. Di sinilah [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) berperan. Fitur ini memungkinkan Anda untuk mendeploy model apa pun dan mengeksposnya sebagai API privat. Setelah dideploy, Anda akan mendapatkan URL yang dapat Anda hubungkan menggunakan kode yang persis sama seperti sebelumnya, dengan hanya mengubah parameter `model`: ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") # or >>> client = InferenceClient() >>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") ``` Perhatikan bahwa Anda tidak dapat menentukan URL dan provider secara bersamaan - keduanya saling eksklusif. URL digunakan untuk terhubung langsung ke endpoint yang telah di-deploy. ### Menggunakan endpoint lokal Anda dapat menggunakan [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) untuk menjalankan chat completion dengan server inferensi lokal (llama.cpp, vllm, litellm server, TGI, mlx, dll.) yang berjalan di mesin Anda sendiri. API-nya harus kompatibel dengan OpenAI API. ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(model="http://localhost:8080") >>> response = client.chat.completions.create( ... messages=[ ... {"role": "user", "content": "What is the capital of France?"} ... ], ... max_tokens=100 ... ) >>> print(response.choices[0].message.content) ``` > [!TIP] > Sama seperti klien Python OpenAI, [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) dapat digunakan untuk menjalankan inferensi Chat Completion dengan endpoint apa pun yang kompatibel dengan REST API OpenAI. ### Autentikasi Autentikasi dapat dilakukan dengan dua cara: **Dialirkan melalui Hugging Face** : Gunakan Hugging Face sebagai proxy untuk mengakses penyedia pihak ketiga. Panggilan akan dialirkan melalui infrastruktur Hugging Face menggunakan kunci penyedia kami, dan penggunaan akan ditagihkan langsung ke akun Hugging Face Anda. Anda dapat melakukan autentikasi menggunakan [User Access Token](https://huggingface.co/docs/hub/security-tokens). Anda dapat memberikan token Hugging Face Anda secara langsung menggunakan parameter `api_key`: ```python >>> client = InferenceClient( provider="replicate", api_key="hf_****" # Your HF token ) ``` Jika Anda *tidak* meneruskan `api_key`, klien akan mencoba menemukan dan menggunakan token yang disimpan secara lokal di mesin Anda. Hal ini biasanya terjadi jika Anda sebelumnya telah masuk. Lihat [Panduan Autentikasi](https://huggingface.co/docs/huggingface_hub/quick-start#authentication) untuk detail tentang login. ```python >>> client = InferenceClient( provider="replicate", token="hf_****" # Your HF token ) ``` **Akses langsung ke penyedia**: Gunakan kunci API Anda sendiri untuk berinteraksi langsung dengan layanan penyedia: ```python >>> client = InferenceClient( provider="replicate", api_key="r8_****" # Your Replicate API key ) ``` Untuk detail lebih lanjut, lihat [dokumentasi harga Inference Providers](https://huggingface.co/docs/inference-providers/pricing#routed-requests-vs-direct-calls). ## Penyedia dan tugas yang didukung Tujuan [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) adalah menyediakan antarmuka termudah untuk menjalankan inferensi pada model Hugging Face, di penyedia mana pun. Ia memiliki API sederhana yang mendukung tugas-tugas yang paling umum. Berikut adalah tabel yang menunjukkan penyedia mana yang mendukung tugas apa: | Tugas | Baseten | Cerebras | Cohere | DeepInfra | fal-ai | Featherless AI | Fireworks AI | Groq | HF Inference | Novita AI | Nscale | OVHcloud AI Endpoints | AI Publik | Replicate | Scaleway | Bersama | Wavespeed | Zai | | --------------------------------------------------- | ------- | -------- | ------ | --------- | ------ | -------------- | ------------ | ---- | ------------ | --------- | ------ | --------------------- | --------- | --------- | -------- | -------- | --------- | --- | | [audio_classification()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.audio_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [audio_to_audio()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.audio_to_audio) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [automatic_speech_recognition()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.automatic_speech_recognition) | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | | [chat_completion()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion) | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | | [document_question_answering()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.document_question_answering) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [feature_extraction()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.feature_extraction) | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | | [fill_mask()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.fill_mask) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [image_classification()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.image_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [image_segmentation()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.image_segmentation) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [image_to_image()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.image_to_image) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | | [image_to_video()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.image_to_video) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | | [image_to_text()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.image_to_text) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [object_detection()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.object_detection) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [question_answering()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.question_answering) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [sentence_similarity()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.sentence_similarity) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [summarization()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.summarization) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [table_question_answering()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.table_question_answering) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [text_classification()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.text_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [text_generation()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.text_generation) | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | | [text_to_image()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_image) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | | [text_to_speech()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_speech) | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | | [text_to_video()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_video) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | | [tabular_classification()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.tabular_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [tabular_regression()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.tabular_regression) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [token_classification()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.token_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [translation()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.translation) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [visual_question_answering()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.visual_question_answering) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [zero_shot_image_classification()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.zero_shot_image_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [zero_shot_classification()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.zero_shot_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | > [!TIP] > Lihat halaman [Tugas](https://huggingface.co/tasks) untuk mempelajari lebih lanjut tentang setiap tugas. ## Kompatibilitas OpenAI Tugas `chat_completion` mengikuti sintaks [klien Python OpenAI](https://github.com/openai/openai-python). Apa artinya bagi Anda? Artinya, jika Anda terbiasa bermain dengan API `OpenAI`, Anda dapat beralih ke `huggingface_hub.InferenceClient` untuk bekerja dengan model open-source hanya dengan memperbarui 2 baris kode! ```diff - from openai import OpenAI + from huggingface_hub import InferenceClient - client = OpenAI( + client = InferenceClient( base_url=..., api_key=..., ) output = client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B-Instruct", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Count to 10"}, ], stream=True, max_tokens=1024, ) for chunk in output: print(chunk.choices[0].delta.content) ``` Dan itu saja! Perubahan wajib yang perlu dilakukan adalah mengganti `from openai import OpenAI` menjadi `from huggingface_hub import InferenceClient` dan `client = OpenAI(...)` menjadi `client = InferenceClient(...)`. Anda dapat memilih model LLM apa pun dari Hugging Face Hub dengan meneruskan id modelnya sebagai parameter `model`. [Ini adalah daftar](https://huggingface.co/models?pipeline_tag=text-generation&other=conversational,text-generation-inference&sort=trending) model yang didukung. Untuk autentikasi, Anda harus meneruskan [User Access Token](https://huggingface.co/settings/tokens) yang valid sebagai `api_key` atau melakukan autentikasi menggunakan `huggingface_hub` (lihat [panduan autentikasi](https://huggingface.co/docs/huggingface_hub/quick-start#authentication)). Semua parameter input dan format output sama persis. Secara khusus, Anda dapat meneruskan `stream=True` untuk menerima token saat mereka dihasilkan. Anda juga dapat menggunakan [AsyncInferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.AsyncInferenceClient) untuk menjalankan inferensi menggunakan `asyncio`: ```diff import asyncio - from openai import AsyncOpenAI + from huggingface_hub import AsyncInferenceClient - client = AsyncOpenAI() + client = AsyncInferenceClient() async def main(): stream = await client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B-Instruct", messages=[{"role": "user", "content": "Say this is a test"}], stream=True, ) async for chunk in stream: print(chunk.choices[0].delta.content or "", end="") asyncio.run(main()) ``` Anda mungkin bertanya-tanya mengapa menggunakan [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) alih-alih klien OpenAI? Ada beberapa alasan untuk itu: 1. [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) dikonfigurasi untuk layanan Hugging Face. Anda tidak perlu menyediakan `base_url` untuk menjalankan model dengan Inference Providers. Anda juga tidak perlu menyediakan `token` atau `api_key` jika mesin Anda sudah masuk dengan benar. 2. [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) dirancang khusus untuk kerangka kerja Text-Generation-Inference (TGI) dan `transformers`, sehingga Anda dapat yakin bahwa klien ini selalu selaras dengan pembaruan terbaru. 3. [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) terintegrasi dengan layanan Inference Endpoints kami, sehingga memudahkan peluncuran Inference Endpoint, pengecekan statusnya, dan eksekusi inferensi di atasnya. Lihat panduan [Inference Endpoints](./inference_endpoints) untuk detail lebih lanjut. > [!TIP] > `InferenceClient.chat.completions.create` hanyalah alias untuk `InferenceClient.chat_completion`. Lihat referensi paket [chat_completion()](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion) untuk detail lebih lanjut. Parameter `base_url` dan `api_key` saat menginstansiasi klien juga merupakan alias untuk `model` dan `token`. Alias ini didefinisikan untuk mengurangi hambatan saat beralih dari `OpenAI` ke `InferenceClient`. ## Pemanggilan Fungsi Function calling memungkinkan LLM berinteraksi dengan alat eksternal, seperti fungsi atau API yang didefinisikan. Hal ini memungkinkan pengguna untuk dengan mudah membangun aplikasi yang disesuaikan dengan kasus penggunaan dan tugas dunia nyata tertentu. `InferenceClient` mengimplementasikan antarmuka pemanggilan alat yang sama dengan OpenAI Chat Completions API. Berikut adalah contoh sederhana pemanggilan alat menggunakan [Novita](https://novita.ai/) sebagai penyedia inferensi: ```python from huggingface_hub import InferenceClient tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get current temperature for a given location.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City and country e.g. Paris, France" } }, "required": ["location"], }, } } ] client = InferenceClient(provider="novita") response = client.chat.completions.create( model="Qwen/Qwen2.5-72B-Instruct", messages=[ { "role": "user", "content": "What's the weather like the next 3 days in London, UK?" } ], tools=tools, tool_choice="auto", ) print(response.choices[0].message.tool_calls[0].function.arguments) ``` > [!TIP] > Silakan merujuk ke dokumentasi penyedia untuk memverifikasi model mana yang didukung oleh mereka untuk Function/Tool Calling. ## Output Terstruktur & Mode JSON InferenceClient mendukung mode JSON untuk respons JSON yang valid secara sintaks dan Structured Outputs untuk respons yang dipaksakan skema. Mode JSON menyediakan data yang dapat dibaca mesin tanpa struktur ketat, sedangkan Structured Outputs menjamin JSON yang valid dan kepatuhan terhadap skema yang telah ditentukan sebelumnya untuk pemrosesan hilir yang andal. Kami mengikuti spesifikasi API OpenAI untuk mode JSON dan Structured Outputs. Anda dapat mengaktifkannya melalui argumen `response_format`. Berikut adalah contoh Structured Outputs menggunakan [Cerebras](https://www.cerebras.ai/) sebagai penyedia inferensi: ```python from huggingface_hub import InferenceClient json_schema = { "name": "book", "schema": { "properties": { "name": { "title": "Name", "type": "string", }, "authors": { "items": {"type": "string"}, "title": "Authors", "type": "array", }, }, "required": ["name", "authors"], "title": "Book", "type": "object", }, "strict": True, } client = InferenceClient(provider="cerebras") completion = client.chat.completions.create( model="Qwen/Qwen3-32B", messages=[ {"role": "system", "content": "Extract the books information."}, {"role": "user", "content": "I recently read 'The Great Gatsby' by F. Scott Fitzgerald."}, ], response_format={ "type": "json_schema", "json_schema": json_schema, }, ) print(completion.choices[0].message) ``` > [!TIP] > Silakan merujuk ke dokumentasi penyedia untuk memverifikasi model mana yang didukung oleh mereka untuk Structured Outputs dan JSON Mode. ## Klien asinkron Versi asinkron dari klien juga disediakan, berdasarkan `asyncio` dan `httpx2`. Semua endpoint API asinkron tersedia melalui [AsyncInferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.AsyncInferenceClient). Inisialisasi dan API-nya sama persis dengan versi sinkron. ```py # Code must be run in an asyncio concurrent context. # $ python -m asyncio >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> image = await client.text_to_image("An astronaut riding a horse on the moon.") >>> image.save("astronaut.png") >>> async for token in await client.text_generation("The Huggingface Hub is", stream=True): ... print(token, end="") a platform for sharing and discussing ML-related content. ``` Untuk informasi lebih lanjut tentang modul `asyncio`, silakan merujuk ke [dokumentasi resmi](https://docs.python.org/3/library/asyncio.html). ## Klien MCP Perpustakaan `huggingface_hub` kini mencakup [MCPClient](/docs/huggingface_hub/main/id/package_reference/mcp#huggingface_hub.MCPClient) eksperimental, yang dirancang untuk memberdayakan Large Language Models (LLM) dengan kemampuan berinteraksi dengan Tools eksternal melalui [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Klien ini memperluas [AsyncInferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.AsyncInferenceClient) untuk mengintegrasikan penggunaan Tools secara mulus. [MCPClient](/docs/huggingface_hub/main/id/package_reference/mcp#huggingface_hub.MCPClient) terhubung ke server MCP (baik skrip `stdio` lokal maupun layanan `http`/`sse` jarak jauh) yang mengekspos tool. Komponen ini memberikan tool tersebut ke LLM (melalui [AsyncInferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.AsyncInferenceClient)). Jika LLM memutuskan untuk menggunakan sebuah tool, [MCPClient](/docs/huggingface_hub/main/id/package_reference/mcp#huggingface_hub.MCPClient) mengelola permintaan eksekusi ke server MCP dan meneruskan output Tool kembali ke LLM, sering kali dengan streaming hasil secara real-time. Pada contoh berikut, kami menggunakan model [Qwen/Qwen2.5-72B-Instruct](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct) melalui penyedia inferensi [Novita](https://novita.ai/). Kami kemudian menambahkan server MCP jarak jauh, dalam hal ini, server SSE yang membuat alat generasi gambar Flux tersedia untuk LLM. ```python import os from huggingface_hub import ChatCompletionInputMessage, ChatCompletionStreamOutput, MCPClient async def main(): async with MCPClient( provider="novita", model="Qwen/Qwen2.5-72B-Instruct", api_key=os.environ["HF_TOKEN"], ) as client: await client.add_mcp_server(type="sse", url="https://evalstate-flux1-schnell.hf.space/gradio_api/mcp/sse") messages = [ { "role": "user", "content": "Generate a picture of a cat on the moon", } ] async for chunk in client.process_single_turn_with_tools(messages): # Log messages if isinstance(chunk, ChatCompletionStreamOutput): delta = chunk.choices[0].delta if delta.content: print(delta.content, end="") # Or tool calls elif isinstance(chunk, ChatCompletionInputMessage): print( f"\nCalled tool '{chunk.name}'. Result: '{chunk.content if len(chunk.content) < 1000 else chunk.content[:1000] + '...'}'" ) if __name__ == "__main__": import asyncio asyncio.run(main()) ``` Untuk pengembangan yang lebih sederhana, kami menawarkan kelas [Agent](/docs/huggingface_hub/main/id/package_reference/mcp#huggingface_hub.Agent) yang lebih tinggi. 'Tiny Agent' ini menyederhanakan pembuatan Agent percakapan dengan mengelola loop chat dan state, pada dasarnya bertindak sebagai pembungkus di sekitar [MCPClient](/docs/huggingface_hub/main/id/package_reference/mcp#huggingface_hub.MCPClient). Dirancang sebagai loop while sederhana yang dibangun tepat di atas [MCPClient](/docs/huggingface_hub/main/id/package_reference/mcp#huggingface_hub.MCPClient). Anda dapat menjalankan Agent ini langsung dari baris perintah: ```bash # install latest version of huggingface_hub with the mcp extra pip install -U huggingface_hub[mcp] # Run an agent that uses the Flux image generation tool tiny-agents run julien-c/flux-schnell-generator ``` Saat diluncurkan, Agent akan memuat dan menampilkan daftar Tools yang telah ditemukan dari server MCP yang terhubung, lalu siap menerima prompt Anda! ## Tips lanjutan Pada bagian di atas, kita telah melihat aspek utama dari [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient). Mari kita mendalami beberapa tips yang lebih lanjut. ### Penagihan Sebagai pengguna HF, Anda mendapatkan kredit bulanan untuk menjalankan inferensi melalui berbagai penyedia di Hub. Jumlah kredit yang Anda dapatkan bergantung pada jenis akun Anda (Free atau PRO atau Enterprise Hub). Anda akan dikenakan biaya untuk setiap permintaan inferensi, sesuai dengan tabel harga penyedia. Secara default, permintaan ditagihkan ke akun pribadi Anda. Namun, Anda dapat mengatur penagihan sehingga permintaan ditagihkan ke organisasi yang Anda ikuti dengan cukup meneruskan `bill_to=""` ke `InferenceClient`. Agar ini berfungsi, organisasi Anda harus berlangganan Enterprise Hub. Untuk detail lebih lanjut tentang penagihan, lihat [panduan ini](https://huggingface.co/docs/api-inference/pricing#features-using-inference-providers). ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(provider="fal-ai", bill_to="openai") >>> image = client.text_to_image( ... "A majestic lion in a fantasy forest", ... model="black-forest-labs/FLUX.1-schnell", ... ) >>> image.save("lion.png") ``` Perhatikan bahwa Anda TIDAK dapat menagih pengguna lain atau organisasi yang tidak Anda ikuti. Jika Anda ingin memberikan kredit kepada orang lain, Anda harus membuat organisasi bersama dengan mereka. ### Timeout Pemanggilan inferensi dapat memakan waktu yang cukup lama. Secara default, [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) akan menunggu "tanpa batas" hingga inferensi selesai. Jika Anda ingin kendali lebih dalam alur kerja Anda, Anda dapat mengatur parameter `timeout` ke nilai tertentu dalam detik. Jika batas waktu habis, [InferenceTimeoutError](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) akan dilempar, yang dapat Anda tangani dalam kode Anda: ```python >>> from huggingface_hub import InferenceClient, InferenceTimeoutError >>> client = InferenceClient(timeout=30) >>> try: ... client.text_to_image(...) ... except InferenceTimeoutError: ... print("Inference timed out after 30s.") ``` ### Input biner Beberapa tugas memerlukan input biner, misalnya saat menangani file gambar atau audio. Dalam kasus ini, [InferenceClient](/docs/huggingface_hub/main/id/package_reference/inference_client#huggingface_hub.InferenceClient) berusaha sedemikian mungkin untuk menerima berbagai tipe: - `bytes` mentah - objek seperti file, dibuka sebagai biner (`with open("audio.flac", "rb") as f: ...`) - path (`str` atau `Path`) yang menunjuk ke file lokal - URL (`str`) yang menunjuk ke file jarak jauh (mis. `https://...`). Dalam kasus ini, file akan diunduh secara lokal sebelum yang dikirim ke API. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg") [{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...] ```