Hub Python Library documentation

Inferenz auf Servern ausführen

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Inferenz auf Servern ausführen

Inferenz ist der Prozess, bei dem ein trainiertes Modell verwendet wird, um Vorhersagen für neue Daten zu treffen. Da dieser Prozess rechenintensiv sein kann, kann die Ausführung auf einem dedizierten Server eine interessante Option sein. Die huggingface_hub Bibliothek bietet eine einfache Möglichkeit, einen Dienst aufzurufen, der die Inferenz für gehostete Modelle durchführt. Es gibt mehrere Dienste, mit denen Sie sich verbinden können:

  • Inferenz API: ein Service, der Ihnen ermöglicht, beschleunigte Inferenz auf der Infrastruktur von Hugging Face kostenlos auszuführen. Dieser Service ist eine schnelle Möglichkeit, um anzufangen, verschiedene Modelle zu testen und AI-Produkte zu prototypisieren.
  • Inferenz Endpunkte: ein Produkt zur einfachen Bereitstellung von Modellen im Produktivbetrieb. Die Inferenz wird von Hugging Face in einer dedizierten, vollständig verwalteten Infrastruktur auf einem Cloud-Anbieter Ihrer Wahl durchgeführt.

Diese Dienste können mit dem InferenceClient Objekt aufgerufen werden. Dieser fungiert als Ersatz für den älteren InferenceApi Client und fügt spezielle Unterstützung für Aufgaben und das Ausführen von Inferenz hinzu, sowohl auf Inferenz API als auch auf Inferenz Endpunkten. Im Abschnitt Legacy InferenceAPI client erfahren Sie, wie Sie zum neuen Client migrieren können.

InferenceClient ist ein Python-Client, der HTTP-Anfragen an unsere APIs stellt. Wenn Sie die HTTP-Anfragen direkt mit Ihrem bevorzugten Tool (curl, postman,…) durchführen möchten, lesen Sie bitte die Dokumentationsseiten der Inferenz API oder der Inferenz Endpunkte.

Für die Webentwicklung wurde ein JS-Client veröffentlicht. Wenn Sie sich für die Spieleentwicklung interessieren, sollten Sie einen Blick auf unser C#-Projekt werfen.

Erste Schritte

Los geht’s mit einer Text-zu-Bild-Aufgabe:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()

>>> image = client.text_to_image("An astronaut riding a horse on the moon.")
>>> image.save("astronaut.png")

Wir haben einen InferenceClient mit den Standardparametern initialisiert. Das Einzige, was Sie wissen müssen, ist die Aufgabe, die Sie ausführen möchten. Standardmäßig wird der Client sich mit der Inferenz API verbinden und ein Modell auswählen, um die Aufgabe abzuschließen. In unserem Beispiel haben wir ein Bild aus einem Textprompt generiert. Der zurückgegebene Wert ist ein PIL.Image-Objekt, das in eine Datei gespeichert werden kann.

Die API ist darauf ausgelegt, einfach zu sein. Nicht alle Parameter und Optionen sind für den Endbenutzer verfügbar oder beschrieben. Schauen Sie auf dieser Seite nach, wenn Sie mehr über alle verfügbaren Parameter für jede Aufgabe erfahren möchten.

Verwendung eines spezifischen Modells

Was ist, wenn Sie ein bestimmtes Modell verwenden möchten? Sie können es entweder als Parameter angeben oder direkt auf Instanzebene spezifizieren:

>>> from huggingface_hub import InferenceClient
# Client für ein spezifisches Modell initialisieren
>>> client = InferenceClient(model="prompthero/openjourney-v4")
>>> client.text_to_image(...)
# Oder nutzen Sie einen generischen Client, geben aber Ihr Modell als Argument an
>>> client = InferenceClient()
>>> client.text_to_image(..., model="prompthero/openjourney-v4")

Es gibt mehr als 200k Modelle im Hugging Face Hub! Jede Aufgabe im InferenceClient kommt mit einem empfohlenen Modell. Beachten Sie, dass die HF-Empfehlung sich im Laufe der Zeit ohne vorherige Ankündigung ändern kann. Daher ist es am besten, ein Modell explizit festzulegen, sobald Sie sich entschieden haben. In den meisten Fällen werden Sie daran interessiert sein, ein Modell zu finden, das speziell auf Ihre Bedürfnisse zugeschnitten ist. Besuchen Sie die Modelle-Seite im Hub, um Ihre Möglichkeiten zu erkunden.

Verwendung einer spezifischen URL

Die oben gesehenen Beispiele nutzen die kostenfrei gehostete Inferenz API. Dies erweist sich als sehr nützlich für Prototyping und schnelles Testen. Wenn Sie bereit sind, Ihr Modell in die Produktion zu übernehmen, müssen Sie eine dedizierte Infrastruktur verwenden. Hier kommen Inferenz Endpunkte ins Spiel. Es ermöglicht Ihnen, jedes Modell zu implementieren und als private API freizugeben. Nach der Implementierung erhalten Sie eine URL, zu der Sie mit genau dem gleichen Code wie zuvor eine Verbindung herstellen können, wobei nur der Modell-Parameter geändert wird:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if")
# oder
>>> client = InferenceClient()
>>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if")

Authentifizierung

Aufrufe, die mit dem InferenceClient gemacht werden, können mit einem User Access Token authentifiziert werden. Standardmäßig wird das auf Ihrem Computer gespeicherte Token verwendet, wenn Sie angemeldet sind (sehen Sie hier, wie Sie sich anmelden können). Wenn Sie nicht angemeldet sind, können Sie Ihr Token als Instanzparameter übergeben:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(token="hf_***")

Die Authentifizierung ist NICHT zwingend erforderlich, wenn Sie die Inferenz API verwenden. Authentifizierte Benutzer erhalten jedoch ein höheres kostenloses Kontingent, um mit dem Service zu arbeiten. Ein Token ist auch zwingend erforderlich, wenn Sie Inferenz auf Ihren privaten Modellen oder auf privaten Endpunkten ausführen möchten.

Unterstützte Aufgaben

Das Ziel von InferenceClient ist es, die einfachste Schnittstelle zum Ausführen von Inferenzen auf Hugging Face-Modellen bereitzustellen. Es verfügt über eine einfache API, die die gebräuchlichsten Aufgaben unterstützt. Hier ist eine Liste der derzeit unterstützten Aufgaben:

Domäne Aufgabe Unterstützt Dokumentation
Audio Audio Classification audio_classification()
Automatic Speech Recognition automatic_speech_recognition()
Text-to-Speech text_to_speech()
Computer Vision Image Classification image_classification()
Image Segmentation image_segmentation()
Image-to-Image image_to_image()
Image-to-Text image_to_text()
Object Detection object_detection()
Text-to-Image text_to_image()
Zero-Shot-Image-Classification zero_shot_image_classification()
Multimodal Documentation Question Answering document_question_answering()
Visual Question Answering visual_question_answering()
NLP Conversational ~InferenceClient.conversational
Feature Extraction feature_extraction()
Fill Mask fill_mask()
Question Answering question_answering()
Sentence Similarity sentence_similarity()
Summarization summarization()
Table Question Answering table_question_answering()
Text Classification text_classification()
Text Generation text_generation()
Token Classification token_classification()
Translation translation()
Zero Shot Classification zero_shot_classification()
Tabular Tabular Classification tabular_classification()
Tabular Regression tabular_regression()

Schauen Sie sich die Aufgaben-Seite an, um mehr über jede Aufgabe zu erfahren, wie man sie verwendet und die beliebtesten Modelle für jede Aufgabe.

Benutzerdefinierte Anfragen

Es ist jedoch nicht immer möglich, alle Anwendungsfälle abzudecken. Für benutzerdefinierte Anfragen bietet die InferenceClient.post() Methode Ihnen die Flexibilität, jede Anfrage an die Inferenz API zu senden. Zum Beispiel können Sie angeben, wie die Eingaben und Ausgaben geparst werden sollen. Im folgenden Beispiel wird das generierte Bild als Roh-Bytes zurückgegeben, anstatt es als PIL Image zu parsen. Dies kann hilfreich sein, wenn Sie Pillow in Ihrer Einrichtung nicht installiert haben und Ihnen nur die Binärinhalt des Bildes wichtig ist. InferenceClient.post() ist auch nützlich, um Aufgaben zu behandeln, die noch nicht offiziell unterstützt werden.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> response = client.post(json={"inputs": "An astronaut riding a horse on the moon."}, model="stabilityai/stable-diffusion-2-1")
>>> response.content # raw bytes
b'...'

Asynchroner Client

Eine asynchrone Version des Clients wird ebenfalls bereitgestellt, basierend auf asyncio und aiohttp. Sie können entweder aiohttp direkt installieren oder das [inference] Extra verwenden:

pip install aiohttp
# oder
pip install --upgrade huggingface_hub[inference]

Nach der Installation sind alle asynchronen API-Endpunkte über AsyncInferenceClient verfügbar. Seine Initialisierung und APIs sind genau gleich wie die synchronisierte Version.

# Der Code muss in einem asyncio-konkurrenten Kontext ausgeführt werden.
# $ 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.

Für weitere Informationen zum asyncio-Modul konsultieren Sie bitte die offizielle Dokumentation.

Fortgeschrittene Tipps

Im obigen Abschnitt haben wir die Hauptaspekte von InferenceClient betrachtet. Lassen Sie uns in einige fortgeschrittene Tipps eintauchen.

Zeitüberschreitung

Bei der Inferenz gibt es zwei Hauptursachen für eine Zeitüberschreitung:

  • Der Inferenzprozess dauert lange, um abgeschlossen zu werden.
  • Das Modell ist nicht verfügbar, beispielsweise wenn die Inferenz API es zum ersten Mal lädt.

Der InferenceClient verfügt über einen globalen Zeitüberschreitungsparameter (timeout), um diese beiden Aspekte zu behandeln. Standardmäßig ist er auf None gesetzt, was bedeutet, dass der Client unendlich lange auf den Abschluss der Inferenz warten wird. Wenn Sie mehr Kontrolle in Ihrem Arbeitsablauf wünschen, können Sie ihn auf einen bestimmten Wert in Sekunden setzen. Wenn die Zeitüberschreitungsverzögerung abläuft, wird ein InferenceTimeoutError ausgelöst. Sie können diesen Fehler abfangen und in Ihrem Code behandeln:

>>> from huggingface_hub import InferenceClient, InferenceTimeoutError
>>> client = InferenceClient(timeout=30)
>>> try:
...     client.text_to_image(...)
... except InferenceTimeoutError:
...     print("Inference timed out after 30s.")

Binäre Eingaben

Einige Aufgaben erfordern binäre Eingaben, zum Beispiel bei der Arbeit mit Bildern oder Audiodateien. In diesem Fall versucht der [`InferenceClient] so permissiv wie möglich zu sein und akzeptiert verschiedene Typen:

  • rohe Bytes
  • ein Datei-ähnliches Objekt, geöffnet als Binär (with open("audio.flac", "rb") as f: ...)
  • ein Pfad (str oder Path) zu einer lokalen Datei
  • eine URL (str) zu einer entfernten Datei (z.B. https://...). In diesem Fall wird die Datei lokal heruntergeladen, bevor sie an die Inferenz API gesendet wird.
>>> 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'}, ...]

Legacy InferenceAPI client

Der InferenceClient dient als Ersatz für den veralteten InferenceApi-Client. Er bietet spezifische Unterstützung für Aufgaben und behandelt Inferenz sowohl auf der Inferenz API als auch auf den Inferenz Endpunkten.

Hier finden Sie eine kurze Anleitung, die Ihnen hilft, von InferenceApi zu InferenceClient zu migrieren.

Initialisierung

Ändern Sie von

>>> from huggingface_hub import InferenceApi
>>> inference = InferenceApi(repo_id="bert-base-uncased", token=API_TOKEN)

zu

>>> from huggingface_hub import InferenceClient
>>> inference = InferenceClient(model="bert-base-uncased", token=API_TOKEN)

Ausführen einer bestimmten Aufgabe

Ändern Sie von

>>> from huggingface_hub import InferenceApi
>>> inference = InferenceApi(repo_id="paraphrase-xlm-r-multilingual-v1", task="feature-extraction")
>>> inference(...)

zu

>>> from huggingface_hub import InferenceClient
>>> inference = InferenceClient()
>>> inference.feature_extraction(..., model="paraphrase-xlm-r-multilingual-v1")

Dies ist der empfohlene Weg, um Ihren Code an InferenceClient anzupassen. Dadurch können Sie von den aufgabenspezifischen Methoden wie feature_extraction profitieren.

Eigene Anfragen ausführen

Ändern Sie von

>>> from huggingface_hub import InferenceApi
>>> inference = InferenceApi(repo_id="bert-base-uncased")
>>> inference(inputs="The goal of life is [MASK].")
[{'sequence': 'the goal of life is life.', 'score': 0.10933292657136917, 'token': 2166, 'token_str': 'life'}]

zu

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> response = client.post(json={"inputs": "The goal of life is [MASK]."}, model="bert-base-uncased")
>>> response.json()
[{'sequence': 'the goal of life is life.', 'score': 0.10933292657136917, 'token': 2166, 'token_str': 'life'}]

Mit Parametern ausführen

Ändern Sie von

>>> from huggingface_hub import InferenceApi
>>> inference = InferenceApi(repo_id="typeform/distilbert-base-uncased-mnli")
>>> inputs = "Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!"
>>> params = {"candidate_labels":["refund", "legal", "faq"]}
>>> inference(inputs, params)
{'sequence': 'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!', 'labels': ['refund', 'faq', 'legal'], 'scores': [0.9378499388694763, 0.04914155602455139, 0.013008488342165947]}

zu

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> inputs = "Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!"
>>> params = {"candidate_labels":["refund", "legal", "faq"]}
>>> response = client.post(json={"inputs": inputs, "parameters": params}, model="typeform/distilbert-base-uncased-mnli")
>>> response.json()
{'sequence': 'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!', 'labels': ['refund', 'faq', 'legal'], 'scores': [0.9378499388694763, 0.04914155602455139, 0.013008488342165947]}
< > Update on GitHub