# 추론 Inference는 학습된 모델을 사용하여 새로운 데이터에 대한 예측을 수행하는 과정입니다. 이 과정은 계산 집약적일 수 있으므로, 전용 또는 외부 서비스에서 실행하는 것이 흥미로운 옵션이 될 수 있습니다. `huggingface_hub` 라이브러리는 Hugging Face Hub에 호스팅된 모델에 대해 여러 서비스에서 추론을 실행하기 위한 통합 인터페이스를 제공합니다: 1. [Inference Providers](https://huggingface.co/docs/inference-providers/index): 서버리스 추론 파트너가 제공하는 수백 개의 머신러닝 모델에 대한 간소화되고 통합된 접근 방식입니다. 이 새로운 접근 방식은 기존의 Serverless Inference API를 기반으로 하며, 세계 수준의 제공업체 덕분에 더 많은 모델, 향상된 성능, 그리고 더 높은 신뢰성을 제공합니다. 지원되는 제공업체 목록은 [문서](https://huggingface.co/docs/inference-providers/index#partners)를 참조하세요. 2. [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index): 모델을 프로덕션에 쉽게 배포할 수 있는 제품입니다. 추론은 사용자가 선택한 클라우드 제공자의 전용, 완전 관리형 인프라에서 Hugging Face에 의해 실행됩니다. 3. 로컬 엔드포인트: 클라이언트를 이러한 로컬 엔드포인트에 연결하여 [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), 또는 [Text Generation Inference (TGI)](https://github.com/huggingface/text-generation-inference)와 같은 로컬 추론 서버로 추론을 실행할 수도 있습니다. 이러한 서비스는 [InferenceClient](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient) 객체를 사용하여 호출할 수 있습니다. 사용 방법에 대한 자세한 내용은 [이 가이드](../guides/inference)를 참고하세요. ## Inference Client[[huggingface_hub.InferenceClient]] #### huggingface_hub.InferenceClient[[huggingface_hub.InferenceClient]] ```python huggingface_hub.InferenceClient(model: str | None = None, provider: typing.Union[typing.Literal['baseten', 'cerebras', 'cohere', 'deepinfra', 'fal-ai', 'featherless-ai', 'fireworks-ai', 'groq', 'hf-inference', 'novita', 'nscale', 'openai', 'ovhcloud', 'publicai', 'replicate', 'scaleway', 'together', 'wavespeed', 'zai-org'], typing.Literal['auto'], NoneType] = None, token: str | None = None, timeout: float | None = None, headers: dict[str, str] | None = None, cookies: dict[str, str] | None = None, bill_to: str | None = None, base_url: str | None = None, api_key: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L124) **매개변수:** model (`str`, `optional`) : 추론을 실행할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID, 예: `meta-llama/Meta-Llama-3-8B-Instruct` 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 기본값은 None이며, 이 경우 해당 작업에 권장되는 모델이 자동으로 선택됩니다. 참고: OpenAI 클라이언트와의 호환성을 높이기 위해 `model`이 `base_url`로 별칭이 지정되었습니다. 이 두 인수는 상호 배타적입니다. 채팅 완성을 위해 `model` 또는 `base_url`로 URL이 전달되면, `(/v1)/chat/completions` 접미 경로가 URL에 추가됩니다. provider (`str`, *선택 사항*) : 추론에 사용할 프로바이더의 이름입니다. `"baseten"`, `"cerebras"`, `"cohere"`, `"deepinfra"`, `"fal-ai"`, `"featherless-ai"`, `"fireworks-ai"`, `"groq"`, `"hf-inference"`, `"novita"`, `"nscale"`, `"openai"`, `"ovhcloud"`, `"publicai"`, `"replicate"`, `"scaleway"`, `"together"`, `"wavespeed"` 또는 `"zai-org"`일 수 있습니다. 기본값은 "auto"입니다. 자동 라우팅으로, 기본적으로 "fastest" 프로바이더를 사용합니다. https://hf.co/settings/inference-providers에서 "cheapest" 또는 "preferred" 프로바이더 순서로 전환할 수 있습니다. model이 URL이거나 `base_url`이 전달되면 `provider`는 사용되지 않습니다. token (`str`, *선택 사항*) : Hugging Face 토큰. 제공되지 않으면 로컬에 저장된 토큰이 기본값으로 사용됩니다. 참고: OpenAI 클라이언트와의 호환성을 높이기 위해 `token`은 `api_key`로 별칭이 지정되었습니다. 이 두 인수는 상호 배타적이며 동작이 완전히 동일합니다. timeout (`float`, `optional`) : 서버로부터 응답을 받을 때까지 대기할 최대 초 수입니다. 기본값은 None이며, 이는 서버가 사용 가능할 때까지 루프를 돌린다는 의미입니다. headers (`dict[str, str]`, `optional`) : 서버로 보낼 추가 헤더입니다. 기본적으로 authorization 및 user-agent 헤더만 전송됩니다. 이 사전의 값은 기본 값을 덮어씁니다. bill_to (`str`, `optional`) : 요청에 사용할 청구 계정입니다. 기본적으로 요청은 사용자의 계정으로 청구됩니다. 요청은 사용자가 멤버로 가입되어 있고 Enterprise Hub에 구독한 조직에만 청구할 수 있습니다. cookies (`dict[str, str]`, `optional`) : 서버에 보낼 추가 쿠키. base_url (`str`, `optional`) : 추론을 실행할 기본 URL입니다. 이는 [InferenceClient](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient)가 `openai.OpenAI` 클라이언트와 동일한 패턴을 따르도록 `model`에서 중복된 인자입니다. `model`이 설정된 경우 사용할 수 없습니다. 기본값은 None입니다. api_key (`str`, `optional`) : 인증에 사용할 토큰. [InferenceClient](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient)가 `openai.OpenAI` 클라이언트와 동일한 패턴을 따르도록 `token`에서 중복된 인자입니다. `token`이 설정된 경우 사용할 수 없습니다. 기본값은 None입니다. 새로운 Inference Client를 초기화합니다. [InferenceClient](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient)는 추론을 수행하기 위한 통합된 경험을 제공하도록 설계되었습니다. 이 클라이언트는 (무료) Inference API, 자체 호스팅된 Inference Endpoints 또는 제3자 Inference Providers와 모두 원활하게 사용할 수 있습니다. #### audio_classification[[huggingface_hub.InferenceClient.audio_classification]] ```python audio_classification(audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, top_k: int | None = None, function_to_apply: typing.Optional[ForwardRef('AudioClassificationOutputTransform')] = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L295) **매개변수:** audio (Union[str, Path, bytes, BinaryIO]) : 분류할 오디오 콘텐츠입니다. 원시 오디오 바이트, 로컬 오디오 파일, 또는 오디오 파일을 가리키는 URL일 수 있습니다. model (`str`, *선택 사항*) : 오디오 분류에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 오디오 분류를 위한 기본 권장 모델이 사용됩니다. top_k (`int`, *선택 사항*) : 지정하면 출력을 상위 K개 가장 확률이 높은 클래스로 제한합니다. function_to_apply (`"AudioClassificationOutputTransform"`, *선택*) : 점수를 가져오기 위해 모델 출력에 적용할 함수입니다. **반환값:** `list[AudioClassificationOutputElement]` 예측된 라벨과 그 신뢰도를 포함하는 [AudioClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.AudioClassificationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 제공된 오디오 콘텐츠에 대해 오디오 분류를 수행합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.audio_classification("audio.flac") [ AudioClassificationOutputElement(score=0.4976358711719513, label='hap'), AudioClassificationOutputElement(score=0.3677836060523987, label='neu'), ... ] ``` #### audio_to_audio[[huggingface_hub.InferenceClient.audio_to_audio]] ```python audio_to_audio(audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L352) **매개변수:** audio (Union[str, Path, bytes, BinaryIO]) : 모델에 사용할 오디오 콘텐츠입니다. 원시 오디오 바이트, 로컬 오디오 파일, 또는 오디오 파일을 가리키는 URL일 수 있습니다. model (`str`, *선택 사항*) : 모델은 오디오 파일을 입력으로 받아 다른 오디오 파일을 반환하는 임의의 모델일 수 있습니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL을 사용할 수 있습니다. 제공되지 않으면 audio_to_audio에 대한 기본 권장 모델이 사용됩니다. **반환값:** `list[AudioToAudioOutputElement]` blob 형식의 오디오 콘텐츠, 콘텐츠 유형, 오디오 라벨을 포함하는 [AudioToAudioOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.AudioToAudioOutputElement) 항목의 목록입니다. **예외:** ``InferenceTimeoutError`` 또는 `HfHubHTTPError` - ``InferenceTimeoutError`` -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 모델에 따라 오디오-오디오와 관련된 여러 작업을 수행합니다(예: 음성 향상, 소스 분리). 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> audio_output = client.audio_to_audio("audio.flac") >>> for i, item in enumerate(audio_output): >>> with open(f"output_{i}.flac", "wb") as f: f.write(item.blob) ``` #### automatic_speech_recognition[[huggingface_hub.InferenceClient.automatic_speech_recognition]] ```python automatic_speech_recognition(audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, extra_body: dict | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L404) **매개변수:** audio (Union[str, Path, bytes, BinaryIO]) : 전사할 콘텐츠입니다. 원시 오디오 바이트, 로컬 오디오 파일, 또는 오디오 파일의 URL일 수 있습니다. model (`str`, *선택 사항*) : ASR에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL을 사용할 수 있습니다. 제공되지 않으면 ASR에 권장되는 기본 모델이 사용됩니다. extra_body (`dict`, *선택 사항*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 해당 제공자의 문서를 참조하세요. **반환값:** [AutomaticSpeechRecognitionOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.AutomaticSpeechRecognitionOutput) 전사된 텍스트와 선택적으로 타임스탬프 청크를 포함하는 항목입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 오디오 콘텐츠에 대해 자동 음성 인식(ASR 또는 오디오-텍스트 변환)을 수행합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.automatic_speech_recognition("hello_world.flac").text "hello world" ``` #### chat_completion[[huggingface_hub.InferenceClient.chat_completion]] ```python chat_completion(messages: list, model: str | None = None, stream: bool = False, frequency_penalty: float | None = None, logit_bias: list[float] | None = None, logprobs: bool | None = None, max_tokens: int | None = None, n: int | None = None, presence_penalty: float | None = None, response_format: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatText, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONSchema, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONObject, NoneType] = None, seed: int | None = None, stop: list[str] | None = None, stream_options: huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputStreamOptions | None = None, temperature: float | None = None, tool_choice: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputToolChoiceClass, ForwardRef('ChatCompletionInputToolChoiceEnum'), NoneType] = None, tool_prompt: str | None = None, tools: list[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputTool] | None = None, top_logprobs: int | None = None, top_p: float | None = None, extra_body: dict | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L531) **매개변수:** messages ([ChatCompletionInputMessage](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionInputMessage) 목록) : 역할과 콘텐츠 쌍으로 구성된 대화 기록. model (`str`, *선택 사항*) : 채팅 완성(chat-completion)에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면, 채팅 기반 텍스트 생성에 대한 기본 권장 모델이 사용됩니다. 자세한 내용은 https://huggingface.co/tasks/text-generation을 참조하세요. `model`이 모델 ID인 경우, 서버에 `model` 파라미터로 전달됩니다. 요청 페이로드에서 `model`을 설정하면서 사용자 정의 URL을 정의하려면, [InferenceClient](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient)를 초기화할 때 `base_url`을 설정해야 합니다. frequency_penalty (`float`, *선택 사항*) : 지금까지의 텍스트에서 이미 존재하는 토큰의 빈도에 따라 새로운 토큰을 페널티합니다. 범위: [-2.0, 2.0]. 기본값은 0.0입니다. logit_bias (`list[float]`, *선택 사항*) : 생성된 출력에서 특정 토큰이 나타날 확률을 조정합니다. logprobs (`bool`, *선택 사항*) : 출력 토큰의 로그 확률을 반환할지 여부입니다. true인 경우, 메시지 콘텐츠에 반환된 각 출력 토큰의 로그 확률을 반환합니다. max_tokens (`int`, *선택 사항*) : 응답에 허용되는 최대 토큰 수입니다. 기본값은 100입니다. n (`int`, *선택 사항*) : 각 프롬프트에 대해 생성할 완성본의 수. presence_penalty (`float`, *선택 사항*) : -2.0과 2.0 사이의 숫자. 양의 값은 현재까지 텍스트에 이미 등장했는지에 따라 새로운 토큰에 페널티를 부과하여, 모델이 새로운 주제에 대해 이야기할 가능성을 높입니다. response_format (`ChatCompletionInputGrammarType()`, *선택*) : 문법 제약 조건. JSONSchema 또는 정규식(regex) 중 하나여야 합니다. seed (선택 사항`int`, *optional*) : 재현 가능한 제어 흐름을 위한 시드. 기본값은 None입니다. stop (`list[str]`, *선택 사항*) : 응답의 종료를 트리거하는 최대 4개의 문자열입니다. 기본값은 None입니다. stream (`bool`, *선택 사항*) : 응답의 실시간 스트리밍을 활성화합니다. 기본값은 False입니다. stream_options ([ChatCompletionInputStreamOptions](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionInputStreamOptions), *선택*) : 스트리밍 completions에 대한 옵션입니다. temperature (`float`, *선택 사항*) : 생성의 무작위성을 제어합니다. 값이 낮을수록 덜 무작위적인 완성 결과를 보장합니다. 범위: [0, 2]. 기본값은 1.0입니다. top_logprobs (`int`, *선택 사항*) : 각 토큰 위치에서 반환할 가장 가능성이 높은 토큰의 수를 0에서 5 사이의 정수로 지정합니다. 각 토큰에는 관련 로그 확률이 포함됩니다. 이 매개변수를 사용하려면 logprobs를 true로 설정해야 합니다. top_p (`float`, *선택 사항*) : 가장 가능성이 높은 다음 단어 중 샘플링할 비율. 0과 1 사이여야 합니다. 기본값은 1.0입니다. tool_choice ([ChatCompletionInputToolChoiceClass](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionInputToolChoiceClass) 또는 `ChatCompletionInputToolChoiceEnum()`, *선택 사항*) : completion에 사용할 도구입니다. 기본값은 "auto"입니다. tool_prompt (`str`, *선택 사항*) : 도구 앞에 추가할 프롬프트입니다. tools ([ChatCompletionInputTool](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionInputTool) 목록, *선택 사항*) : 모델이 호출할 수 있는 도구의 목록입니다. 현재 도구는 함수만 지원합니다. 모델이 JSON 입력을 생성할 수 있는 함수 목록을 제공하려면 이 항목을 사용하세요. extra_body (`dict`, *선택 사항*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 해당 제공자의 문서를 참조하세요. **반환값:** [ChatCompletionOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionOutput) 또는 [ChatCompletionStreamOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionStreamOutput)의 Iterable 서버에서 반환된 생성 텍스트: - `stream=False`인 경우, 생성된 텍스트는 [ChatCompletionOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionOutput)로 반환됩니다(기본값). - `stream=True`인 경우, 생성된 텍스트가 [ChatCompletionStreamOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionStreamOutput)의 시퀀스로 토큰 단위로 반환됩니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 언어 모델을 사용하여 대화를 완료하는 방법입니다. > [!TIP] > `client.chat_completion` 메서드는 OpenAI 클라이언트와의 호환성을 위해 `client.chat.completions.create`로 별칭이 지정되어 있습니다. 입력과 출력은 완전히 동일하며, 두 문법 중 어느 것을 사용하더라도 동일한 결과를 얻습니다. OpenAI 호환성에 대한 자세한 내용은 [추론 가이드](https://huggingface.co/docs/huggingface_hub/guides/inference#openai-compatibility)를 참고하세요. > [!TIP] > `extra_body` 인수를 사용하여 모델에 프로바이더별 매개변수를 전달할 수 있습니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> messages = [{"role": "user", "content": "What is the capital of France?"}] >>> client = InferenceClient("meta-llama/Meta-Llama-3-8B-Instruct") >>> 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 ) ) ``` 스트리밍을 사용한 예시: ```py >>> from huggingface_hub import InferenceClient >>> messages = [{"role": "user", "content": "What is the capital of France?"}] >>> client = InferenceClient("meta-llama/Meta-Llama-3-8B-Instruct") >>> for token in client.chat_completion(messages, max_tokens=10, stream=True): ... print(token) ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content='The', role='assistant'), index=0, finish_reason=None)], created=1710498504) ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' capital', role='assistant'), index=0, finish_reason=None)], created=1710498504) (...) ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' may', role='assistant'), index=0, finish_reason=None)], created=1710498504) ``` OpenAI 문법을 사용한 예시: ```py # instead of `from openai import OpenAI` from huggingface_hub import InferenceClient # instead of `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) ``` 추가(프로바이더별) 매개변수를 사용하여 서드파티 프로바이더를 직접 사용하는 예시입니다. 사용량은 Together AI 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="together", # Use Together AI provider ... api_key="", # Pass your Together API key directly ... ) >>> client.chat_completion( ... model="meta-llama/Meta-Llama-3-8B-Instruct", ... messages=[{"role": "user", "content": "What is the capital of France?"}], ... extra_body={"safety_model": "Meta-Llama/Llama-Guard-7b"}, ... ) ``` Hugging Face Routing을 통해 서드파티 제공업체를 사용하는 예시입니다. 사용량은 Hugging Face 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="novita", # Use Novita provider ... api_key="hf_...", # Pass your HF token ... ) >>> client.chat_completion( ... model="meta-llama/Meta-Llama-3-8B-Instruct", ... messages=[{"role": "user", "content": "What is the capital of France?"}], ... ) ``` 이미지 + 텍스트를 입력으로 사용하는 예시: ```py >>> from huggingface_hub import InferenceClient # provide a remote URL >>> image_url ="https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" # or a base64-encoded image >>> image_path = "/path/to/image.jpeg" >>> with open(image_path, "rb") as f: ... base64_image = base64.b64encode(f.read()).decode("utf-8") >>> image_url = f"data:image/jpeg;base64,{base64_image}" >>> client = InferenceClient("meta-llama/Llama-3.2-11B-Vision-Instruct") >>> output = client.chat.completions.create( ... messages=[ ... { ... "role": "user", ... "content": [ ... { ... "type": "image_url", ... "image_url": {"url": image_url}, ... }, ... { ... "type": "text", ... "text": "Describe this image in one sentence.", ... }, ... ], ... }, ... ], ... ) >>> output The image depicts the iconic Statue of Liberty situated in New York Harbor, New York, on a clear day. ``` 도구를 사용한 예시: ```py >>> client = InferenceClient("meta-llama/Meta-Llama-3-70B-Instruct") >>> messages = [ ... { ... "role": "system", ... "content": "Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous.", ... }, ... { ... "role": "user", ... "content": "What's the weather like the next 3 days in San Francisco, CA?", ... }, ... ] >>> tools = [ ... { ... "type": "function", ... "function": { ... "name": "get_current_weather", ... "description": "Get the current weather", ... "parameters": { ... "type": "object", ... "properties": { ... "location": { ... "type": "string", ... "description": "The city and state, e.g. San Francisco, CA", ... }, ... "format": { ... "type": "string", ... "enum": ["celsius", "fahrenheit"], ... "description": "The temperature unit to use. Infer this from the users location.", ... }, ... }, ... "required": ["location", "format"], ... }, ... }, ... }, ... { ... "type": "function", ... "function": { ... "name": "get_n_day_weather_forecast", ... "description": "Get an N-day weather forecast", ... "parameters": { ... "type": "object", ... "properties": { ... "location": { ... "type": "string", ... "description": "The city and state, e.g. San Francisco, CA", ... }, ... "format": { ... "type": "string", ... "enum": ["celsius", "fahrenheit"], ... "description": "The temperature unit to use. Infer this from the users location.", ... }, ... "num_days": { ... "type": "integer", ... "description": "The number of days to forecast", ... }, ... }, ... "required": ["location", "format", "num_days"], ... }, ... }, ... }, ... ] >>> response = client.chat_completion( ... model="meta-llama/Meta-Llama-3-70B-Instruct", ... messages=messages, ... tools=tools, ... tool_choice="auto", ... max_tokens=500, ... ) >>> response.choices[0].message.tool_calls[0].function ChatCompletionOutputFunctionDefinition( arguments={ 'location': 'San Francisco, CA', 'format': 'fahrenheit', 'num_days': 3 }, name='get_n_day_weather_forecast', description=None ) ``` response_format를 사용한 예시: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient("meta-llama/Meta-Llama-3-70B-Instruct") >>> messages = [ ... { ... "role": "user", ... "content": "I saw a puppy a cat and a raccoon during my bike ride in the park. What did I see and when?", ... }, ... ] >>> response_format = { ... "type": "json", ... "value": { ... "properties": { ... "location": {"type": "string"}, ... "activity": {"type": "string"}, ... "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5}, ... "animals": {"type": "array", "items": {"type": "string"}}, ... }, ... "required": ["location", "activity", "animals_seen", "animals"], ... }, ... } >>> response = client.chat_completion( ... messages=messages, ... response_format=response_format, ... max_tokens=500, ... ) >>> response.choices[0].message.content '{ y": "bike ride", ": ["puppy", "cat", "raccoon"], _seen": 3, n": "park"}' ``` #### document_question_answering[[huggingface_hub.InferenceClient.document_question_answering]] ```python document_question_answering(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], question: str, model: str | None = None, doc_stride: int | None = None, handle_impossible_answer: bool | None = None, lang: str | None = None, max_answer_len: int | None = None, max_question_len: int | None = None, max_seq_len: int | None = None, top_k: int | None = None, word_boxes: list[list[float] | str] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L933) **매개변수:** image (`Union[str, Path, bytes, BinaryIO]`) : 컨텍스트에 사용할 입력 이미지입니다. 원시 바이트, 이미지 파일, 또는 온라인 이미지의 URL일 수 있습니다. question (`str`) : 답변할 질문. model (`str`, *선택 사항*) : 문서 질의응답 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 문서 질의응답 모델이 사용됩니다. 기본값은 None입니다. doc_stride (`int`, *선택 사항*) : 문서의 단어가 모델의 질문과 함께 들어갈 수 없을 정도로 길면, 일부 중복을 포함하여 여러 청크로 나뉩니다. 이 인수는 해당 중복의 크기를 제어합니다. handle_impossible_answer (`bool`, *선택 사항*) : 불가능을 답변으로 허용할지 여부 lang (`str`, *선택 사항*) : OCR 실행 시 사용할 언어입니다. 기본값은 영어입니다. max_answer_len (`int`, *선택 사항*) : 예측된 답변의 최대 길이 (예: 이 길이보다 짧은 답변만 고려됨). max_question_len (`int`, *선택 사항*) : 토큰화 후 질문의 최대 길이입니다. 필요할 경우 잘립니다. max_seq_len (`int`, *선택 사항*) : 모델에 전달되는 각 청크의 토큰 단위로, 전체 문장(컨텍스트 + 질문)의 최대 길이입니다. 필요할 경우 doc_stride를 오버랩으로 사용하여 컨텍스트를 여러 청크로 분할합니다. top_k (`int`, *선택 사항*) : 반환할 답변의 수(가능성 순서대로 선택됩니다). 컨텍스트 내에서 사용할 수 있는 옵션이 충분하지 않으면 top_k보다 적은 답변을 반환할 수 있습니다. word_boxes (`list[Union[list[float], str`, *optional*) : 단어와 바운딩 박스(0->1000으로 정규화)의 목록입니다. 제공된 경우, 추론 과정에서 OCR 단계를 건너뛰고 제공된 바운딩 박스를 대신 사용합니다. **반환값:** `list[DocumentQuestionAnsweringOutputElement]` 예측된 라벨, 관련 확률, 단어 ID, 페이지 번호를 포함하는 [DocumentQuestionAnsweringOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.DocumentQuestionAnsweringOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 문서 이미지에 대한 질문에 답합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.document_question_answering(image="https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png", question="What is the invoice number?") [DocumentQuestionAnsweringOutputElement(answer='us-001', end=16, score=0.9999666213989258, start=16)] ``` #### feature_extraction[[huggingface_hub.InferenceClient.feature_extraction]] ```python feature_extraction(text: str | list[str], normalize: bool | None = None, prompt_name: str | None = None, truncate: bool | None = None, truncation_direction: typing.Optional[typing.Literal['left', 'right']] = None, dimensions: int | None = None, encoding_format: typing.Optional[typing.Literal['float', 'base64']] = None, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1020) **매개변수:** text (*str* 또는 *list[str]*) : 임베딩할 텍스트 또는 텍스트 목록. model (*str*, *optional*) : feature extraction 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 feature extraction 모델이 사용됩니다. 기본값은 None입니다. normalize (*bool*, *optional*) : 임베딩을 정규화할지 여부. Text-Embedding-Inference로 구동되는 서버에서만 사용할 수 있습니다. prompt_name (*str*, *optional*) : The name of the prompt that should be used by for encoding. If not set, no prompt will be applied. Must be a key in the *Sentence Transformers* configuration *prompts* dictionary. For example if `prompt_name` is "query" and the `prompts` is &lcub;"query": "query: ",...}, then the sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?" because the prompt text will be prepended before any text to encode. truncate (*bool*, *optional*) : 임베딩을 잘라낼지 여부. Text-Embedding-Inference로 구동되는 서버에서만 사용할 수 있습니다. truncation_direction (*Literal["left", "right"]*, *선택*) : *truncate=True*가 전달될 때 입력의 어느 쪽을 잘라낼지 지정합니다. dimensions (*int*, *optional*) : 결과 출력 임베딩이 가져야 할 차원의 수입니다. OpenAI 호환 임베딩 엔드포인트에서만 사용할 수 있습니다. encoding_format (*Literal["float", "base64"]*, *선택*) : 출력 임베딩의 형식입니다. "float" 또는 "base64" 중 하나입니다. OpenAI 호환 임베딩 엔드포인트에서만 사용할 수 있습니다. **반환값:** `*np.ndarray*` float32 numpy 배열로 입력 텍스트를 나타내는 임베딩. **예외:** [*InferenceTimeoutError*] 또는 [*HfHubHTTPError*] - [*InferenceTimeoutError*] -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - [*HfHubHTTPError*] -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트 또는 텍스트 배치에 대해 임베딩을 생성합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.feature_extraction("Hi, who are you?") array([[ 2.424802 , 2.93384 , 1.1750331 , ..., 1.240499, -0.13776633, -0.7889173 ], [-0.42943227, -0.6364878 , -1.693462 , ..., 0.41978157, -2.4336355 , 0.6162071 ], ..., [ 0.28552425, -0.928395 , -1.2077185 , ..., 0.76810825, -2.1069427 , 0.6236161 ]], dtype=float32) ``` #### fill_mask[[huggingface_hub.InferenceClient.fill_mask]] ```python fill_mask(text: str, model: str | None = None, targets: list[str] | None = None, top_k: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1103) **매개변수:** text (`str`) : 채울 문자열이며, [MASK] 토큰을 포함해야 합니다 (마스크의 정확한 이름은 모델 카드에서 확인하세요). model (`str`, *선택 사항*) : fill mask 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 fill mask 모델이 사용됩니다. targets (`list[str`, *optional*) : 전달되면, 모델은 전체 어휘를 검색하는 대신 전달된 대상에 점수를 제한합니다. 제공된 대상이 모델 어휘에 없으면 토큰화되고, 생성된 첫 번째 토큰이 사용됩니다(경고와 함께, 이는 더 느릴 수 있음). top_k (`int`, *선택 사항*) : 전달되면 반환할 예측의 수를 재정의합니다. **반환값:** `list[FillMaskOutputElement]` 예측된 라벨, 관련 확률, 토큰 참조, 완성된 텍스트를 포함하는 [FillMaskOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.FillMaskOutputElement) 항목의 목록 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 누락된 단어(정확히 말하면 토큰)로 빈칸을 채웁니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.fill_mask("The goal of life is .") [ FillMaskOutputElement(score=0.06897063553333282, token=11098, token_str=' happiness', sequence='The goal of life is happiness.'), FillMaskOutputElement(score=0.06554922461509705, token=45075, token_str=' immortality', sequence='The goal of life is immortality.') ] ``` #### get_endpoint_info[[huggingface_hub.InferenceClient.get_endpoint_info]] ```python get_endpoint_info(model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L3250) **매개변수:** model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. **반환값:** `dict[str, Any]` 엔드포인트에 대한 정보. 배포된 엔드포인트에 대한 정보를 가져옵니다. 이 엔드포인트는 Text-Generation-Inference(TGI) 또는 Text-Embedding-Inference(TEI)로 구동되는 엔드포인트에서만 사용할 수 있습니다. `transformers`로 구동되는 엔드포인트는 빈 페이로드를 반환합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient("meta-llama/Meta-Llama-3-70B-Instruct") >>> client.get_endpoint_info() { 'model_id': 'meta-llama/Meta-Llama-3-70B-Instruct', 'model_sha': None, 'model_dtype': 'torch.float16', 'model_device_type': 'cuda', 'model_pipeline_tag': None, 'max_concurrent_requests': 128, 'max_best_of': 2, 'max_stop_sequences': 4, 'max_input_length': 8191, 'max_total_tokens': 8192, 'waiting_served_ratio': 0.3, 'max_batch_total_tokens': 1259392, 'max_waiting_tokens': 20, 'max_batch_size': None, 'validation_workers': 32, 'max_client_batch_size': 4, 'version': '2.0.2', 'sha': 'dccab72549635c7eb5ddb17f43f0b7cdff07c214', 'docker_label': 'sha-dccab72' } ``` #### health_check[[huggingface_hub.InferenceClient.health_check]] ```python health_check(model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L3308) **매개변수:** model (`str`, *선택 사항*) : Inference Endpoint의 URL입니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. **반환값:** `bool` 모든 것이 정상적으로 작동하는 경우 True입니다. 배포된 엔드포인트의 상태를 확인합니다. Health check은 Text-Generation-Inference(TGI) 또는 Text-Embedding-Inference(TEI) 기반의 Inference Endpoints에서만 사용할 수 있습니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient("https://jzgu0buei5.us-east-1.aws.endpoints.huggingface.cloud") >>> client.health_check() True ``` #### image_classification[[huggingface_hub.InferenceClient.image_classification]] ```python image_classification(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, function_to_apply: typing.Optional[ForwardRef('ImageClassificationOutputTransform')] = None, top_k: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1159) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 분류할 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 이미지 분류에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 이미지 분류를 위한 기본 권장 모델이 사용됩니다. function_to_apply (`"ImageClassificationOutputTransform"`, *선택*) : 점수를 가져오기 위해 모델 출력에 적용할 함수입니다. top_k (`int`, *선택 사항*) : 지정하면 출력을 상위 K개 가장 확률이 높은 클래스로 제한합니다. **반환값:** `list[ImageClassificationOutputElement]` 예측된 라벨과 관련 확률을 포함하는 [ImageClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ImageClassificationOutputElement) 항목의 목록 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 주어진 이미지에 대해 이미지 분류를 수행합니다. 예: ```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") [ImageClassificationOutputElement(label='Blenheim spaniel', score=0.9779096841812134), ...] ``` #### image_segmentation[[huggingface_hub.InferenceClient.image_segmentation]] ```python image_segmentation(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, mask_threshold: float | None = None, overlap_mask_area_threshold: float | None = None, subtask: typing.Optional[ForwardRef('ImageSegmentationSubtask')] = None, threshold: float | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1209) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 분할할 이미지. 원시 바이트, 이미지 파일, 온라인 이미지의 URL 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 이미지 분할에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 이미지 분할을 위한 기본 권장 모델이 사용됩니다. mask_threshold (`float`, *선택 사항*) : 예측된 마스크를 바이너리 값으로 변환할 때 사용할 임계값. overlap_mask_area_threshold (`float`, *선택 사항*) : 작고 분리된 세그먼트를 제거하기 위한 마스크 오버랩 임계값. subtask (`"ImageSegmentationSubtask"`, *선택 사항*) : 모델의 기능에 따라 수행할 분할 작업입니다. threshold (`float`, *선택 사항*) : 예측된 마스크를 필터링할 확률 임계값. **반환값:** `list[ImageSegmentationOutputElement]` 분할된 마스크와 관련 속성을 포함하는 [ImageSegmentationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ImageSegmentationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 주어진 이미지에 대해 이미지 분할을 수행합니다. > [!WARNING] > 이미지를 다루려면 `PIL`이 설치되어 있어야 합니다(`pip install Pillow`). 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.image_segmentation("cat.jpg") [ImageSegmentationOutputElement(score=0.989008, label='LABEL_184', mask=), ...] ``` #### image_to_image[[huggingface_hub.InferenceClient.image_to_image]] ```python image_to_image(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], prompt: str | None = None, negative_prompt: str | None = None, num_inference_steps: int | None = None, guidance_scale: float | None = None, model: str | None = None, target_size: huggingface_hub.inference._generated.types.image_to_image.ImageToImageTargetSize | None = None, **kwargs) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1277) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 번역을 위한 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. prompt (`str`, *선택 사항*) : 이미지 생성을 안내하는 텍스트 프롬프트입니다. negative_prompt (`str`, *선택 사항*) : 이미지 생성에서 포함하지 말아야 할 내용을 안내하는 프롬프트 하나입니다. num_inference_steps (`int`, *선택 사항*) : 확산 모델용입니다. 디노이징 단계의 수를 지정합니다. 디노이징 단계가 많을수록 일반적으로 더 높은 품질의 이미지를 생성하지만, 추론 속도는 느려집니다. guidance_scale (`float`, *선택 사항*) : 확산 모델용입니다. guidance scale 값이 높을수록 모델은 텍스트 프롬프트와 밀접하게 연결된 이미지를 생성하도록 장려되지만, 이미지 품질이 낮아지는 대가를 치릅니다. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. target_size (`ImageToImageTargetSize`, *선택 사항*) : 출력 이미지의 픽셀 단위 크기입니다. 이 매개변수는 일부 프로바이더와 특정 모델에서만 지원됩니다. 지원하지 않는 경우 무시됩니다. **반환값:** `Image` 변환된 이미지. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 이미지-이미지 변환을 수행합니다. > [!WARNING] > 이미지를 다루려면 `PIL`이 설치되어 있어야 합니다(`pip install Pillow`). 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> image = client.image_to_image("cat.jpg", prompt="turn the cat into a tiger") >>> image.save("tiger.jpg") ``` #### image_to_text[[huggingface_hub.InferenceClient.image_to_text]] ```python image_to_text(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1432) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 캡션할 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. **반환값:** [ImageToTextOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ImageToTextOutput) 생성된 텍스트. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 입력 이미지를 받아 텍스트를 반환합니다. 모델은 사용 사례(이미지 캡셔닝, 광학 문자 인식(OCR), Pix2Struct 등)에 따라 매우 다른 출력을 생성할 수 있습니다. 모델의 고유한 특성에 대해 자세히 알아보려면 모델 카드를 확인해 보세요. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.image_to_text("cat.jpg") 'a cat standing in a grassy field ' >>> client.image_to_text("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg") 'a dog laying on the grass next to a flower pot ' ``` #### image_to_video[[huggingface_hub.InferenceClient.image_to_video]] ```python image_to_video(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, prompt: str | None = None, negative_prompt: str | None = None, num_frames: float | None = None, num_inference_steps: int | None = None, guidance_scale: float | None = None, seed: int | None = None, target_size: huggingface_hub.inference._generated.types.image_to_video.ImageToVideoTargetSize | None = None, **kwargs) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1353) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 비디오 생성에 사용할 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. prompt (`str`, *선택 사항*) : 비디오 생성을 안내하는 텍스트 프롬프트입니다. negative_prompt (`str`, *선택 사항*) : 비디오 생성에서 포함하지 말아야 할 내용을 안내하는 프롬프트 하나입니다. num_frames (`float`, *선택 사항*) : num_frames 파라미터는 생성할 비디오 프레임 수를 결정합니다. num_inference_steps (`int`, *선택 사항*) : 확산 모델용입니다. 디노이징 단계의 수를 지정합니다. 디노이징 단계가 많을수록 일반적으로 더 높은 품질의 이미지를 생성하지만, 추론 속도는 느려집니다. guidance_scale (`float`, *선택 사항*) : 확산 모델용입니다. guidance scale 값이 높을수록 모델은 텍스트 프롬프트와 밀접하게 연결된 비디오를 생성하도록 장려되지만, 이미지 품질이 낮아지는 대가를 치릅니다. seed (`int`, *선택 사항*) : 비디오 생성에 사용할 시드입니다. target_size (`ImageToVideoTargetSize`, *선택 사항*) : 출력 비디오 프레임의 픽셀 단위 크기입니다. num_inference_steps (`int`, *선택 사항*) : 디노이징 단계 수. 디노이징 단계가 많을수록 일반적으로 더 높은 품질의 비디오를 생성하지만, 추론 속도가 느려집니다. seed (`int`, *선택 사항*) : 난수 생성기의 시드입니다. **반환값:** `bytes` 생성된 비디오. 입력 이미지에서 비디오를 생성합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> video = client.image_to_video("cat.jpg", model="Wan-AI/Wan2.2-I2V-A14B", prompt="turn the cat into a tiger") >>> with open("tiger.mp4", "wb") as f: ... f.write(video) ``` #### object_detection[[huggingface_hub.InferenceClient.object_detection]] ```python object_detection(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, threshold: float | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1478) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 객체를 감지할 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 객체 감지에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 객체 감지를 위한 기본 권장 모델(DETR)이 사용됩니다. threshold (`float`, *선택 사항*) : 예측을 수행하는 데 필요한 확률입니다. **반환값:** `list[ObjectDetectionOutputElement]` 바운딩 박스와 관련 속성을 포함하는 [ObjectDetectionOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ObjectDetectionOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` 또는 ``ValueError`` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. - ``ValueError`` -- 요청 출력이 List가 아닌 경우. 지정된 모델을 사용하여 주어진 이미지에서 객체 감지를 수행합니다. > [!WARNING] > 이미지를 다루려면 `PIL`이 설치되어 있어야 합니다(`pip install Pillow`). 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.object_detection("people.jpg") [ObjectDetectionOutputElement(score=0.9486683011054993, label='person', box=ObjectDetectionBoundingBox(xmin=59, ymin=39, xmax=420, ymax=510)), ...] ``` #### 질문_답변[[huggingface_hub.InferenceClient.question_answering]] ```python question_answering(question: str, context: str, model: str | None = None, align_to_words: bool | None = None, doc_stride: int | None = None, handle_impossible_answer: bool | None = None, max_answer_len: int | None = None, max_question_len: int | None = None, max_seq_len: int | None = None, top_k: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1526) **매개변수:** question (`str`) : 답변할 질문. context (`str`) : 질문의 컨텍스트. model (`str`) : 질문 응답 작업에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. align_to_words (`bool`, *선택 사항*) : 답변을 실제 단어에 맞게 정렬을 시도합니다. 공백으로 구분되는 언어에서 품질을 향상시킵니다. 공백으로 구분되지 않는 언어(일본어 또는 중국어 등)에서는 품질이 저하될 수 있습니다 doc_stride (`int`, *선택 사항*) : 컨텍스트가 모델의 질문과 함께 들어갈 수 없을 정도로 너무 길면, 일부 중복을 포함하여 여러 청크로 나뉩니다. 이 인수는 해당 중복의 크기를 제어합니다. handle_impossible_answer (`bool`, *선택 사항*) : 불가능을 답변으로 허용할지 여부. max_answer_len (`int`, *선택 사항*) : 예측된 답변의 최대 길이 (예: 이 길이보다 짧은 답변만 고려됨). max_question_len (`int`, *선택 사항*) : 토큰화 후 질문의 최대 길이입니다. 필요할 경우 잘립니다. max_seq_len (`int`, *선택 사항*) : 모델에 전달되는 각 청크의 토큰 수로 측정된 전체 문장(컨텍스트 + 질문)의 최대 길이입니다. 필요할 경우 docStride를 오버랩으로 사용하여 컨텍스트를 여러 청크로 나눕니다. top_k (`int`, *선택 사항*) : 반환할 답변의 수(가능성 순서대로 선택됩니다). 컨텍스트 내에서 사용할 수 있는 옵션이 충분하지 않으면 topk보다 적은 수의 답변이 반환됩니다. **반환값:** Union[`QuestionAnsweringOutputElement`, list[QuestionAnsweringOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.QuestionAnsweringOutputElement)] top_k가 1이거나 제공되지 않으면 단일 `QuestionAnsweringOutputElement`를 반환합니다. top_k가 1보다 크면 `QuestionAnsweringOutputElement`의 목록을 반환합니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트에서 질문에 대한 답변을 검색합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.question_answering(question="What's my name?", context="My name is Clara and I live in Berkeley.") QuestionAnsweringOutputElement(answer='Clara', end=16, score=0.9326565265655518, start=11) ``` #### sentence_similarity[[huggingface_hub.InferenceClient.sentence_similarity]] ```python sentence_similarity(sentence: str, other_sentences: list, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1610) **매개변수:** sentence (`str`) : 다른 문장과 비교할 주 문장입니다. other_sentences (`list[str]`) : 비교할 문장 목록. model (`str`, *선택 사항*) : 문장 유사도 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 문장 유사도 모델이 사용됩니다. 기본값은 None입니다. **반환값:** `list[float]` 입력 텍스트를 나타내는 임베딩. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 임베딩을 비교하여 문장과 다른 문장 목록 간의 의미적 유사도를 계산합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.sentence_similarity( ... "Machine learning is so easy.", ... other_sentences=[ ... "Deep learning is so straightforward.", ... "This is so difficult, like rocket science.", ... "I can't believe how much I struggled with this.", ... ], ... ) [0.7785726189613342, 0.45876261591911316, 0.2906220555305481] ``` #### 요약[[huggingface_hub.InferenceClient.summarization]] ```python summarization(text: str, model: str | None = None, clean_up_tokenization_spaces: bool | None = None, generate_parameters: dict[str, typing.Any] | None = None, truncation: typing.Optional[ForwardRef('SummarizationTruncationStrategy')] = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1663) **매개변수:** text (`str`) : 요약할 입력 텍스트. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 요약에 권장되는 기본 모델이 사용됩니다. clean_up_tokenization_spaces (`bool`, *선택 사항*) : 텍스트 출력의 잠재적인 추가 공백을 정리할지 여부. generate_parameters (`dict[str, Any]`, *선택 사항*) : 텍스트 생성 알고리즘의 추가 매개변수 설정. truncation (`"SummarizationTruncationStrategy"`, *선택 사항*) : 사용할 절단 전략입니다. **반환값:** [SummarizationOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.SummarizationOutput) 생성된 요약 텍스트. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 주어진 텍스트의 요약을 생성합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.summarization("The Eiffel tower...") SummarizationOutput(generated_text="The Eiffel tower is one of the most famous landmarks in the world....") ``` #### table_question_answering[[huggingface_hub.InferenceClient.table_question_answering]] ```python table_question_answering(table: dict, query: str, model: str | None = None, padding: typing.Optional[ForwardRef('Padding')] = None, sequential: bool | None = None, truncation: bool | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1721) **매개변수:** table (`str`) : 항목이 헤더이고 리스트가 모든 값인 리스트의 딕셔너리로 표현된 데이터 테이블입니다. 모든 리스트는 동일한 크기를 가져야 합니다. query (`str`) : 테이블에 질문하고 싶은 일반 텍스트 쿼리입니다. model (`str`) : 테이블 질의응답 작업에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. padding (`"Padding"`, *선택*) : 패딩을 활성화하고 제어합니다. sequential (`bool`, *선택 사항*) : 추론을 순차적으로 수행할지 배치로 수행할지를 결정합니다. 배치 처리가 더 빠르지만, SQA와 같은 모델은 대화형 특성상 시퀀스 내 관계를 추출하려면 추론을 순차적으로 수행해야 합니다. truncation (`bool`, *선택 사항*) : 잘라내기(truncation)를 활성화하고 제어합니다. **반환값:** [TableQuestionAnsweringOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TableQuestionAnsweringOutputElement) 답변, 좌표, 셀 및 사용된 어그리게이터를 포함하는 테이블 질문 응답 출력 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. … 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> query = "How many stars does the transformers repository have?" >>> table = {"Repository": ["Transformers", "Datasets", "Tokenizers"], "Stars": ["36542", "4512", "3934"]} >>> client.table_question_answering(table, query, model="google/tapas-base-finetuned-wtq") TableQuestionAnsweringOutputElement(answer='36542', coordinates=[[0, 1]], cells=['36542'], aggregator='AVERAGE') ``` #### tabular_classification[[huggingface_hub.InferenceClient.tabular_classification]] ```python tabular_classification(table: dict, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1783) **매개변수:** table (`dict[str, Any]`) : 분류할 속성의 집합. model (`str`, *선택 사항*) : 표형 분류 작업에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 표형 분류 모델이 사용됩니다. 기본값은 None입니다. **반환값:** `List` … **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. … 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> table = { ... "fixed_acidity": ["7.4", "7.8", "10.3"], ... "volatile_acidity": ["0.7", "0.88", "0.32"], ... "citric_acid": ["0", "0", "0.45"], ... "residual_sugar": ["1.9", "2.6", "6.4"], ... "chlorides": ["0.076", "0.098", "0.073"], ... "free_sulfur_dioxide": ["11", "25", "5"], ... "total_sulfur_dioxide": ["34", "67", "13"], ... "density": ["0.9978", "0.9968", "0.9976"], ... "pH": ["3.51", "3.2", "3.23"], ... "sulphates": ["0.56", "0.68", "0.82"], ... "alcohol": ["9.4", "9.8", "12.6"], ... } >>> client.tabular_classification(table=table, model="julien-c/wine-quality") ["5", "5", "5"] ``` #### tabular_regression[[huggingface_hub.InferenceClient.tabular_regression]] ```python tabular_regression(table: dict, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1838) **매개변수:** table (`dict[str, Any]`) : 테이블에 저장된 속성의 집합입니다. 타겟을 예측하는 데 사용되는 속성은 수치형과 범주형 모두일 수 있습니다. model (`str`, *선택 사항*) : 표형 회귀 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 표형 회귀 모델이 사용됩니다. 기본값은 None입니다. **반환값:** `List` 예측된 수치형 대상 값의 목록 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 테이블의 속성/특징 집합이 주어졌을 때 수치형 대상 값을 예측하는 작업입니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> table = { ... "Height": ["11.52", "12.48", "12.3778"], ... "Length1": ["23.2", "24", "23.9"], ... "Length2": ["25.4", "26.3", "26.5"], ... "Length3": ["30", "31.2", "31.1"], ... "Species": ["Bream", "Bream", "Bream"], ... "Width": ["4.02", "4.3056", "4.6961"], ... } >>> client.tabular_regression(table, model="scikit-learn/Fish-Weight") [110, 120, 130] ``` #### text_classification[[huggingface_hub.InferenceClient.text_classification]] ```python text_classification(text: str, model: str | None = None, top_k: int | None = None, function_to_apply: typing.Optional[ForwardRef('TextClassificationOutputTransform')] = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L1888) **매개변수:** text (`str`) : 분류할 문자열. model (`str`, *선택 사항*) : 텍스트 분류 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 텍스트 분류 모델이 사용됩니다. 기본값은 None입니다. top_k (`int`, *선택 사항*) : 지정하면 출력을 상위 K개 가장 확률이 높은 클래스로 제한합니다. function_to_apply (`"TextClassificationOutputTransform"`, *선택*) : 점수를 가져오기 위해 모델 출력에 적용할 함수입니다. **반환값:** `list[TextClassificationOutputElement]` 예측된 라벨과 관련 확률을 포함하는 [TextClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TextClassificationOutputElement) 항목의 목록 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트에 대해 텍스트 분류(예: 감정 분석)를 수행합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.text_classification("I like you") [ TextClassificationOutputElement(label='POSITIVE', score=0.9998695850372314), TextClassificationOutputElement(label='NEGATIVE', score=0.0001304351753788069), ] ``` #### text_generation[[huggingface_hub.InferenceClient.text_generation]] ```python text_generation(prompt: str, details: bool | None = None, stream: bool | None = None, model: str | None = None, adapter_id: str | None = None, best_of: int | None = None, decoder_input_details: bool | None = None, do_sample: bool | None = None, frequency_penalty: float | None = None, grammar: huggingface_hub.inference._generated.types.text_generation.TextGenerationInputGrammarType | None = None, max_new_tokens: int | None = None, repetition_penalty: float | None = None, return_full_text: bool | None = None, seed: int | None = None, stop: list[str] | None = None, temperature: float | None = None, top_k: int | None = None, top_n_tokens: int | None = None, top_p: float | None = None, truncate: int | None = None, typical_p: float | None = None, watermark: bool | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L2091) **매개변수:** prompt (`str`) : 입력 텍스트. details (`bool`, *선택 사항*) : 기본적으로 text_generation은 문자열을 반환합니다. 토큰, 확률, 시드, 종료 이유 등 상세한 출력을 원하면 `details=True`를 전달하세요. `text-generation-inference` 백엔드로 실행되는 모델에서만 사용할 수 있습니다. stream (`bool`, *선택 사항*) : 기본적으로 text_generation은 생성된 전체 텍스트를 반환합니다. 토큰 스트림을 반환하려면 `stream=True`를 전달하세요. `text-generation-inference` 백엔드로 실행되는 모델에서만 사용할 수 있습니다. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. adapter_id (`str`, *선택 사항*) : Lora 어댑터 ID. best_of (`int`, *선택 사항*) : best_of개의 시퀀스를 생성하고 가장 높은 토큰 logprobs를 가진 시퀀스를 반환합니다. decoder_input_details (`bool`, *선택 사항*) : 디코더 입력 토큰의 logprobs와 id를 반환합니다. 이를 적용하려면 `details=True`도 함께 설정해야 합니다. 기본값은 `False`입니다. do_sample (`bool`, *선택 사항*) : logits 샘플링 활성화 frequency_penalty (`float`, *선택 사항*) : -2.0과 2.0 사이의 숫자. 양의 값은 텍스트에서 이미 나타난 빈도에 따라 새로운 토큰을 벌점 처리하여, 모델이 동일한 줄을 그대로 반복할 가능성을 낮춥니다. grammar ([TextGenerationInputGrammarType](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TextGenerationInputGrammarType), *선택*) : 문법 제약 조건. JSONSchema 또는 정규식(regex) 중 하나여야 합니다. max_new_tokens (`int`, *선택 사항*) : 생성할 토큰의 최대 개수. 기본값은 100입니다. repetition_penalty (`float`, *선택 사항*) : 반복 페널티를 위한 매개변수입니다. 1.0은 페널티가 없음을 의미합니다. 자세한 내용은 [이 논문](https://arxiv.org/pdf/1909.05858.pdf)을 참고하세요. return_full_text (`bool`, *선택 사항*) : 생성된 텍스트 앞에 프롬프트를 붙일지 여부 seed (`int`, *선택 사항*) : 무작위 샘플링 시드 stop (`list[str]`, *선택 사항*) : `stop`의 멤버가 생성되면 토큰 생성을 중단합니다. temperature (`float`, *선택 사항*) : logits 분포를 모듈레이션하는 데 사용되는 값입니다. top_n_tokens (`int`, *선택 사항*) : 샘플링된 토큰만 반환하는 대신, 각 생성 단계에서 가장 가능성이 높은 `top_n_tokens` 토큰에 대한 정보를 반환합니다. top_k (`int`, *optional`) : top-k-filtering을 위해 유지할 가장 높은 확률의 어휘 토큰 수. top_p (`float`, *optional`) : If set to < 1, only the smallest set of most probable tokens with probabilities that add up to `top_p` or higher are kept for generation. truncate (`int`, *optional`) : 입력 토큰을 지정된 크기로 잘라냅니다. typical_p (`float`, *선택 사항`): Typical Decoding의 질량 값. 자세한 내용은 [자연어 생성을 위한 Typical Decoding](https://arxiv.org/abs/2202.00666)을 참조하세요 watermark (`bool`, *선택 사항*) : [대형 언어 모델을 위한 워터마크](https://arxiv.org/abs/2301.10226)를 사용한 워터마킹 **반환값:** `Union[str, TextGenerationOutput, Iterable[str], Iterable[TextGenerationStreamOutput]]` 서버에서 반환된 생성 텍스트: - `stream=False`이고 `details=False`인 경우, 생성된 텍스트는 `str`로 반환됩니다(기본값). - `stream=True`이고 `details=False`인 경우, 생성된 텍스트가 `Iterable[str]`로 토큰 단위로 반환됩니다. - `stream=False`이고 `details=True`인 경우, 생성된 텍스트는 [TextGenerationOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TextGenerationOutput)로 더 자세한 정보와 함께 반환됩니다. - `details=True`이고 `stream=True`인 경우, 생성된 텍스트는 [TextGenerationStreamOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TextGenerationStreamOutput)의 반복 가능한 객체로 토큰 단위로 반환됩니다. **예외:** ``ValidationError`` 또는 [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - ``ValidationError`` -- 입력 값이 유효하지 않은 경우. 서버에 HTTP 호출이 수행되지 않습니다. - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 이 주어지면, 다음 텍스트를 생성합니다. > [!TIP] > 채팅 메시지에서 응답을 생성하려면 [InferenceClient.chat_completion()](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion) 메서드를 사용해야 합니다. 이 메서드는 단일 텍스트 프롬프트 대신 메시지 목록을 받아들이며, 채팅 템플릿 처리를 자동으로 수행합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() # Case 1: generate text >>> client.text_generation("The huggingface_hub library is ", max_new_tokens=12) '100% open source and built to be easy to use.' # Case 2: iterate over the generated tokens. Useful for large generation. >>> for token in client.text_generation("The huggingface_hub library is ", max_new_tokens=12, stream=True): ... print(token) 100 % open source and built to be easy to use . # Case 3: get more details about the generation process. >>> client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True) TextGenerationOutput( generated_text='100% open source and built to be easy to use.', details=TextGenerationDetails( finish_reason='length', generated_tokens=12, seed=None, prefill=[ TextGenerationPrefillOutputToken(id=487, text='The', logprob=None), TextGenerationPrefillOutputToken(id=53789, text=' hugging', logprob=-13.171875), (...) TextGenerationPrefillOutputToken(id=204, text=' ', logprob=-7.0390625) ], tokens=[ TokenElement(id=1425, text='100', logprob=-1.0175781, special=False), TokenElement(id=16, text='%', logprob=-0.0463562, special=False), (...) TokenElement(id=25, text='.', logprob=-0.5703125, special=False) ], best_of_sequences=None ) ) # Case 4: iterate over the generated tokens with more details. # Last object is more complete, containing the full generated text and the finish reason. >>> for details in client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True, stream=True): ... print(details) ... TextGenerationStreamOutput(token=TokenElement(id=1425, text='100', logprob=-1.0175781, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=16, text='%', logprob=-0.0463562, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=1314, text=' open', logprob=-1.3359375, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=3178, text=' source', logprob=-0.28100586, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=273, text=' and', logprob=-0.5961914, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=3426, text=' built', logprob=-1.9423828, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-1.4121094, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=314, text=' be', logprob=-1.5224609, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=1833, text=' easy', logprob=-2.1132812, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-0.08520508, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=745, text=' use', logprob=-0.39453125, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement( id=25, text='.', logprob=-0.5703125, special=False), generated_text='100% open source and built to be easy to use.', details=TextGenerationStreamOutputStreamDetails(finish_reason='length', generated_tokens=12, seed=None) ) # Case 5: generate constrained output using grammar >>> response = client.text_generation( ... prompt="I saw a puppy a cat and a raccoon during my bike ride in the park", ... model="HuggingFaceH4/zephyr-orpo-141b-A35b-v0.1", ... max_new_tokens=100, ... repetition_penalty=1.3, ... grammar={ ... "type": "json", ... "value": { ... "properties": { ... "location": {"type": "string"}, ... "activity": {"type": "string"}, ... "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5}, ... "animals": {"type": "array", "items": {"type": "string"}}, ... }, ... "required": ["location", "activity", "animals_seen", "animals"], ... }, ... }, ... ) >>> json.loads(response) { "activity": "bike riding", "animals": ["puppy", "cat", "raccoon"], "animals_seen": 3, "location": "park" } ``` #### text_to_image[[huggingface_hub.InferenceClient.text_to_image]] ```python text_to_image(prompt: str, negative_prompt: str | None = None, height: int | None = None, width: int | None = None, num_inference_steps: int | None = None, guidance_scale: float | None = None, model: str | None = None, scheduler: str | None = None, seed: int | None = None, extra_body: dict[str, typing.Any] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L2418) **매개변수:** prompt (`str`) : 이미지를 생성할 프롬프트. negative_prompt (`str`, *선택 사항*) : 이미지 생성에서 포함하지 말아야 할 내용을 안내하는 프롬프트 하나입니다. height (`int`, *선택 사항*) : 출력 이미지의 픽셀 단위 높이 width (`int`, *선택 사항*) : 출력 이미지의 픽셀 단위 너비 num_inference_steps (`int`, *선택 사항*) : 디노이징 단계의 수입니다. 디노이징 단계가 많을수록 일반적으로 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 생성합니다. guidance_scale (`float`, *선택 사항*) : guidance scale 값이 높을수록 모델은 텍스트 프롬프트와 밀접하게 연결된 이미지를 생성하도록 장려하지만, 값이 너무 높으면 포화(saturation) 및 기타 아티팩트가 발생할 수 있습니다. model (`str`, *선택 사항*) : 추론에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 텍스트-이미지 모델이 사용됩니다. 기본값은 None입니다. scheduler (`str`, *선택 사항*) : 호환되는 스케줄러로 덮어씁니다. seed (`int`, *선택 사항*) : 난수 생성기의 시드입니다. extra_body (`dict[str, Any]`, *선택*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 제공자의 문서를 참조하세요. **반환값:** `Image` 생성된 이미지. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 주어진 텍스트를 기반으로 이미지를 생성합니다. > [!WARNING] > 이미지를 다루려면 `PIL`이 설치되어 있어야 합니다(`pip install Pillow`). > [!TIP] > `extra_body` 인수를 사용하여 모델에 프로바이더별 매개변수를 전달할 수 있습니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> image = client.text_to_image("An astronaut riding a horse on the moon.") >>> image.save("astronaut.png") >>> image = client.text_to_image( ... "An astronaut riding a horse on the moon.", ... negative_prompt="low resolution, blurry", ... model="stabilityai/stable-diffusion-2-1", ... ) >>> image.save("better_astronaut.png") ``` 세 번째 제공업체를 직접 사용하는 예시입니다. 사용량은 fal.ai 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="fal-ai", # Use fal.ai provider ... api_key="fal-ai-api-key", # Pass your fal.ai API key ... ) >>> image = client.text_to_image( ... "A majestic lion in a fantasy forest", ... model="black-forest-labs/FLUX.1-schnell", ... ) >>> image.save("lion.png") ``` Hugging Face Routing을 통해 서드파티 제공업체를 사용하는 예시입니다. 사용량은 Hugging Face 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", # Use replicate provider ... api_key="hf_...", # Pass your HF token ... ) >>> image = client.text_to_image( ... "An astronaut riding a horse on the moon.", ... model="black-forest-labs/FLUX.1-dev", ... ) >>> image.save("astronaut.png") ``` 추가 매개변수를 사용하여 Replicate 제공자를 사용하는 예시 ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", # Use replicate provider ... api_key="hf_...", # Pass your HF token ... ) >>> image = client.text_to_image( ... "An astronaut riding a horse on the moon.", ... model="black-forest-labs/FLUX.1-schnell", ... extra_body={"output_quality": 100}, ... ) >>> image.save("astronaut.png") ``` #### text_to_speech[[huggingface_hub.InferenceClient.text_to_speech]] ```python text_to_speech(text: str, model: str | None = None, do_sample: bool | None = None, early_stopping: typing.Union[bool, ForwardRef('TextToSpeechEarlyStoppingEnum'), NoneType] = None, epsilon_cutoff: float | None = None, eta_cutoff: float | None = None, max_length: int | None = None, max_new_tokens: int | None = None, min_length: int | None = None, min_new_tokens: int | None = None, num_beam_groups: int | None = None, num_beams: int | None = None, penalty_alpha: float | None = None, temperature: float | None = None, top_k: int | None = None, top_p: float | None = None, typical_p: float | None = None, use_cache: bool | None = None, extra_body: dict[str, typing.Any] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L2655) **매개변수:** text (`str`) : 합성할 텍스트. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 텍스트-음성 변환 모델이 사용됩니다. 기본값은 None입니다. do_sample (`bool`, *선택 사항*) : 새로운 토큰을 생성할 때 탐욕적 디코딩 대신 샘플링을 사용할지 여부. early_stopping (`Union[bool, "TextToSpeechEarlyStoppingEnum"]`, *선택*) : beam 기반 방법의 종료 조건을 제어합니다. epsilon_cutoff (`float`, *선택 사항*) : 0과 1 사이의 float 값으로 설정하면, epsilon_cutoff보다 큰 조건부 확률을 가진 토큰만 샘플링됩니다. 논문에서는 모델 크기에 따라 권장 값이 3e-4에서 9e-4 범위로 제시됩니다. 자세한 내용은 [Truncation Sampling as Language Model Desmoothing](https://hf.co/papers/2210.15191)을 참조하세요. eta_cutoff (`float`, *선택 사항*) : Eta 샘플링은 로컬 전형 샘플링과 epsilon 샘플링의 하이브리드입니다. 0과 1 사이의 float 값으로 설정하면, 해당 토큰이 eta_cutoff 또는 sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits)))보다 큰 경우에만 고려됩니다. 후자의 항은 직관적으로 sqrt(eta_cutoff)으로 스케일링된 다음 토큰의 기대 확률입니다. 논문에서는 모델 크기에 따라 권장 값이 3e-4에서 2e-3 범위로 제시됩니다. 자세한 내용은 [Truncation Sampling as Language Model Desmoothing](https://hf.co/papers/2210.15191)을 참조하세요. max_length (`int`, *선택 사항*) : 입력을 포함하여 생성된 텍스트의 최대 길이(토큰 단위). max_new_tokens (`int`, *선택 사항*) : 생성할 최대 토큰 수입니다. max_length보다 우선합니다. min_length (`int`, *선택 사항*) : 입력을 포함하여 생성된 텍스트의 최소 길이(토큰 단위). min_new_tokens (`int`, *선택 사항*) : 생성할 최소 토큰 수입니다. min_length보다 우선합니다. num_beam_groups (`int`, *선택 사항*) : 서로 다른 beam 그룹 간 다양성을 보장하기 위해 num_beams를 나누는 그룹 수. 자세한 내용은 [이 논문](https://hf.co/papers/1610.02424)을 참조하세요. num_beams (`int`, *선택 사항*) : beam search에 사용할 beam의 수. penalty_alpha (`float`, *선택 사항*) : contrastive search decoding에서 모델의 신뢰도와 퇴화 페널티를 균형 있게 조절하는 값입니다. temperature (`float`, *선택 사항*) : 다음 토큰의 확률을 조절하는 데 사용되는 값. top_k (`int`, *선택 사항*) : top-k-filtering을 위해 유지할 가장 높은 확률의 어휘 토큰 수. top_p (`float`, *선택 사항*) : float < 1로 설정하면, 생성 시 확률의 합이 top_p 이상인 가장 확률이 높은 최소 토큰 집합만 유지됩니다. typical_p (`float`, *선택 사항*) : Local typicality는 이미 생성된 부분 텍스트가 주어졌을 때, 다음으로 대상 토큰을 예측하는 조건부 확률이 다음으로 무작위 토큰을 예측하는 기대 조건부 확률과 얼마나 유사한지를 측정합니다. float < 1로 설정하면, 확률의 합이 typical_p 이상인 가장 로컬적으로 전형적인 토큰의 가장 작은 집합만 생성을 위해 유지됩니다. 자세한 내용은 [이 논문](https://hf.co/papers/2202.00666)을 참조하세요. use_cache (`bool`, *선택 사항*) : 디코딩 속도를 높이기 위해 모델이 이전의 마지막 키/값 어텐션을 사용해야 하는지 여부 extra_body (`dict[str, Any]`, *선택*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 제공자의 문서를 참조하세요. **반환값:** `bytes` 생성된 오디오. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트를 발음하는 목소리의 오디오를 합성합니다. > [!TIP] > `extra_body` 인수를 사용하여 모델에 프로바이더별 매개변수를 전달할 수 있습니다. 예: ```py >>> from pathlib import Path >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> audio = client.text_to_speech("Hello world") >>> Path("hello_world.flac").write_bytes(audio) ``` 세 번째 제공업체를 직접 사용하는 예시입니다. 사용량은 Replicate 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", ... api_key="your-replicate-api-key", # Pass your Replicate API key directly ... ) >>> audio = client.text_to_speech( ... text="Hello world", ... model="OuteAI/OuteTTS-0.3-500M", ... ) >>> Path("hello_world.flac").write_bytes(audio) ``` Hugging Face Routing을 통해 서드파티 제공업체를 사용하는 예시입니다. 사용량은 Hugging Face 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", ... api_key="hf_...", # Pass your HF token ... ) >>> audio =client.text_to_speech( ... text="Hello world", ... model="OuteAI/OuteTTS-0.3-500M", ... ) >>> Path("hello_world.flac").write_bytes(audio) ``` 추가 매개변수를 사용하여 Replicate 제공자를 사용하는 예시 ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", # Use replicate provider ... api_key="hf_...", # Pass your HF token ... ) >>> audio = client.text_to_speech( ... "Hello, my name is Kororo, an awesome text-to-speech model.", ... model="hexgrad/Kokoro-82M", ... extra_body={"voice": "af_nicole"}, ... ) >>> Path("hello.flac").write_bytes(audio) ``` fal.ai에서 "YuE-s1-7B-anneal-en-cot"을 사용한 음악 생성 예시 ```py >>> from huggingface_hub import InferenceClient >>> lyrics = ''' ... [verse] ... In the town where I was born ... Lived a man who sailed to sea ... And he told us of his life ... In the land of submarines ... So we sailed on to the sun ... 'Til we found a sea of green ... And we lived beneath the waves ... In our yellow submarine ... [chorus] ... We all live in a yellow submarine ... Yellow submarine, yellow submarine ... We all live in a yellow submarine ... Yellow submarine, yellow submarine ... ''' >>> genres = "pavarotti-style tenor voice" >>> client = InferenceClient( ... provider="fal-ai", ... model="m-a-p/YuE-s1-7B-anneal-en-cot", ... api_key=..., ... ) >>> audio = client.text_to_speech(lyrics, extra_body={"genres": genres}) >>> with open("output.mp3", "wb") as f: ... f.write(audio) ``` #### text_to_video[[huggingface_hub.InferenceClient.text_to_video]] ```python text_to_video(prompt: str, model: str | None = None, guidance_scale: float | None = None, negative_prompt: list[str] | None = None, num_frames: float | None = None, num_inference_steps: int | None = None, seed: int | None = None, extra_body: dict[str, typing.Any] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L2558) **매개변수:** prompt (`str`) : 비디오를 생성할 프롬프트. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 텍스트-비디오 모델이 사용됩니다. 기본값은 None입니다. guidance_scale (`float`, *선택 사항*) : guidance scale 값이 높을수록 모델은 텍스트 프롬프트와 밀접하게 연결된 비디오를 생성하도록 장려하지만, 값이 너무 높으면 포화(saturation) 및 기타 아티팩트가 발생할 수 있습니다. negative_prompt (`list[str]`, *선택 사항*) : 비디오 생성에서 포함하지 말아야 할 내용을 안내하는 하나 이상의 프롬프트. num_frames (`float`, *선택 사항*) : num_frames 파라미터는 생성할 비디오 프레임 수를 결정합니다. num_inference_steps (`int`, *선택 사항*) : 디노이징 단계 수. 디노이징 단계가 많을수록 일반적으로 더 높은 품질의 비디오를 생성하지만, 추론 속도가 느려집니다. seed (`int`, *선택 사항*) : 난수 생성기의 시드입니다. extra_body (`dict[str, Any]`, *선택*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 제공자의 문서를 참조하세요. **반환값:** `bytes` 생성된 비디오. 주어진 텍스트를 기반으로 비디오를 생성합니다. > [!TIP] > `extra_body` 인수를 사용하여 모델에 프로바이더별 매개변수를 전달할 수 있습니다. 예: 세 번째 제공업체를 직접 사용하는 예시입니다. 사용량은 fal.ai 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="fal-ai", # Using fal.ai provider ... api_key="fal-ai-api-key", # Pass your fal.ai API key ... ) >>> video = client.text_to_video( ... "A majestic lion running in a fantasy forest", ... model="tencent/HunyuanVideo", ... ) >>> with open("lion.mp4", "wb") as file: ... file.write(video) ``` Hugging Face Routing을 통해 서드파티 제공업체를 사용하는 예시입니다. 사용량은 Hugging Face 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", # Using replicate provider ... api_key="hf_...", # Pass your HF token ... ) >>> video = client.text_to_video( ... "A cat running in a park", ... model="genmo/mochi-1-preview", ... ) >>> with open("cat.mp4", "wb") as file: ... file.write(video) ``` #### token_classification[[huggingface_hub.InferenceClient.token_classification]] ```python token_classification(text: str, model: str | None = None, aggregation_strategy: typing.Optional[ForwardRef('TokenClassificationAggregationStrategy')] = None, ignore_labels: list[str] | None = None, stride: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L2863) **매개변수:** text (`str`) : 분류할 문자열. model (`str`, *선택 사항*) : 토큰 분류 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 토큰 분류 모델이 사용됩니다. 기본값은 None입니다. aggregation_strategy (`"TokenClassificationAggregationStrategy"`, *선택 사항*) : 모델 예측을 기반으로 토큰을 융합하는 데 사용되는 전략 ignore_labels (`list[str`, *optional*) : 무시할 레이블 목록 stride (`int`, *선택 사항*) : 입력 텍스트를 분할할 때 청크 사이에 중복되는 토큰의 수입니다. **반환값:** `list[TokenClassificationOutputElement]` 엔티티 그룹, 신뢰도 점수, 단어, 시작 및 끝 인덱스를 포함하는 [TokenClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TokenClassificationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트에 대해 토큰 분류를 수행합니다. 일반적으로 문장 분석에 사용되며, 문법적 분석 또는 텍스트에 포함된 키워드를 이해하기 위한 Named Entity Recognition(NER)에 활용됩니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica") [ TokenClassificationOutputElement( entity_group='PER', score=0.9971321225166321, word='Sarah Jessica Parker', start=11, end=31, ), TokenClassificationOutputElement( entity_group='PER', score=0.9773476123809814, word='Jessica', start=52, end=59, ) ] ``` #### 번역[[huggingface_hub.InferenceClient.translation]] ```python translation(text: str, model: str | None = None, src_lang: str | None = None, tgt_lang: str | None = None, clean_up_tokenization_spaces: bool | None = None, truncation: typing.Optional[ForwardRef('TranslationTruncationStrategy')] = None, generate_parameters: dict[str, typing.Any] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L2938) **매개변수:** text (`str`) : 번역할 문자열. model (`str`, *선택 사항*) : 번역 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 번역 모델이 사용됩니다. 기본값은 None입니다. src_lang (`str`, *선택 사항*) : 텍스트의 원본 언어입니다. 여러 언어에서 번역할 수 있는 모델의 경우 필수입니다. tgt_lang (`str`, *선택 사항*) : 번역할 대상 언어입니다. 여러 언어로 번역할 수 있는 모델의 경우 필수입니다. clean_up_tokenization_spaces (`bool`, *선택 사항*) : 텍스트 출력의 잠재적인 추가 공백을 정리할지 여부. truncation (`"TranslationTruncationStrategy"`, *선택 사항*) : 사용할 절단 전략입니다. generate_parameters (`dict[str, Any]`, *선택 사항*) : 텍스트 생성 알고리즘의 추가 매개변수 설정. **반환값:** [TranslationOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TranslationOutput) 생성된 번역된 텍스트. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` 또는 ``ValueError`` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. - ``ValueError`` -- `src_lang`와 `tgt_lang` 인수 중 하나만 제공된 경우. 한 언어의 텍스트를 다른 언어로 변환합니다. 특정 사용 사례에 가장 적합한 모델을 선택하는 방법에 대한 자세한 내용은 https://huggingface.co/tasks/translation 을 참고하세요. 원본 언어와 대상 언어는 일반적으로 모델에 따라 달라집니다. 그러나 일부 모델에서는 원본 언어와 대상 언어를 지정할 수 있습니다. 이러한 모델 중 하나를 사용하는 경우 `src_lang` 및 `tgt_lang` 인수를 사용하여 관련 정보를 전달할 수 있습니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.translation("My name is Wolfgang and I live in Berlin") 'Mein Name ist Wolfgang und ich lebe in Berlin.' >>> client.translation("My name is Wolfgang and I live in Berlin", model="Helsinki-NLP/opus-mt-en-fr") TranslationOutput(translation_text='Je m'appelle Wolfgang et je vis à Berlin.') ``` 언어 지정: ```py >>> client.translation("My name is Sarah Jessica Parker but you can call me Jessica", model="facebook/mbart-large-50-many-to-many-mmt", src_lang="en_XX", tgt_lang="fr_XX") "Mon nom est Sarah Jessica Parker mais vous pouvez m'appeler Jessica" ``` #### visual_question_answering[[huggingface_hub.InferenceClient.visual_question_answering]] ```python visual_question_answering(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], question: str, model: str | None = None, top_k: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L3027) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 컨텍스트에 사용할 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. question (`str`) : 답변할 질문. model (`str`, *선택 사항*) : 시각 질의응답 작업에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 시각 질의응답 모델이 사용됩니다. 기본값은 None입니다. top_k (`int`, *선택 사항*) : 반환할 답변의 수(가능성 순서대로 선택됩니다). 컨텍스트 내에서 사용할 수 있는 옵션이 충분하지 않으면 topk보다 적은 수의 답변이 반환됩니다. **반환값:** `list[VisualQuestionAnsweringOutputElement]` 예측된 라벨과 관련 확률을 포함하는 [VisualQuestionAnsweringOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.VisualQuestionAnsweringOutputElement) 항목의 목록 **예외:** ``InferenceTimeoutError`` 또는 `HfHubHTTPError` - ``InferenceTimeoutError`` -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 이미지를 기반으로 열린 질문을 답변합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.visual_question_answering( ... image="https://huggingface.co/datasets/mishig/sample_images/resolve/main/tiger.jpg", ... question="What is the animal doing?" ... ) [ VisualQuestionAnsweringOutputElement(score=0.778609573841095, answer='laying down'), VisualQuestionAnsweringOutputElement(score=0.6957435607910156, answer='sitting'), ] ``` #### zero_shot_classification[[huggingface_hub.InferenceClient.zero_shot_classification]] ```python zero_shot_classification(text: str, candidate_labels: list, multi_label: bool | None = False, hypothesis_template: str | None = None, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L3086) **매개변수:** text (`str`) : 분류할 입력 텍스트. candidate_labels (`list[str]`) : 텍스트를 분류할 수 있는 클래스 라벨의 집합. multi_label (`bool`, *선택 사항*) : 여러 후보 라벨이 동시에 참일 수 있는지 여부입니다. false인 경우, 각 시퀀스에 대해 라벨 가능성의 합이 1이 되도록 점수가 정규화됩니다. true인 경우, 라벨은 독립적으로 간주되며 각 후보에 대해 확률이 정규화됩니다. hypothesis_template (`str`, *선택 사항*) : `candidate_labels`와 함께 사용되며, 플레이스홀더를 후보 레이블로 대체하여 텍스트 분류를 시도하는 데 사용되는 문장입니다. model (`str`, *선택 사항*) : 추론에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 제공되지 않으면 기본 권장 zero-shot 분류 모델이 사용됩니다. **반환값:** `list[ZeroShotClassificationOutputElement]` 예측된 라벨과 그 신뢰도를 포함하는 [ZeroShotClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ZeroShotClassificationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 입력으로 텍스트와 해당 텍스트를 분류할 후보 라벨 집합을 제공합니다. `multi_label=False`인 예시: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> text = ( ... "A new model offers an explanation for how the Galilean satellites formed around the solar system's" ... "largest world. Konstantin Batygin did not set out to solve one of the solar system's most puzzling" ... " mysteries when he went for a run up a hill in Nice, France." ... ) >>> labels = ["space & cosmos", "scientific discovery", "microbiology", "robots", "archeology"] >>> client.zero_shot_classification(text, labels) [ ZeroShotClassificationOutputElement(label='scientific discovery', score=0.7961668968200684), ZeroShotClassificationOutputElement(label='space & cosmos', score=0.18570658564567566), ZeroShotClassificationOutputElement(label='microbiology', score=0.00730885099619627), ZeroShotClassificationOutputElement(label='archeology', score=0.006258360575884581), ZeroShotClassificationOutputElement(label='robots', score=0.004559356719255447), ] >>> client.zero_shot_classification(text, labels, multi_label=True) [ ZeroShotClassificationOutputElement(label='scientific discovery', score=0.9829297661781311), ZeroShotClassificationOutputElement(label='space & cosmos', score=0.755190908908844), ZeroShotClassificationOutputElement(label='microbiology', score=0.0005462635890580714), ZeroShotClassificationOutputElement(label='archeology', score=0.00047131875180639327), ZeroShotClassificationOutputElement(label='robots', score=0.00030448526376858354), ] ``` `multi_label=True`와 사용자 정의 `hypothesis_template`를 사용한 예시: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.zero_shot_classification( ... text="I really like our dinner and I'm very happy. I don't like the weather though.", ... candidate_labels=["positive", "negative", "pessimistic", "optimistic"], ... multi_label=True, ... hypothesis_template="This text is {} towards the weather" ... ) [ ZeroShotClassificationOutputElement(label='negative', score=0.9231801629066467), ZeroShotClassificationOutputElement(label='pessimistic', score=0.8760990500450134), ZeroShotClassificationOutputElement(label='optimistic', score=0.0008674879791215062), ZeroShotClassificationOutputElement(label='positive', score=0.0005250611575320363) ] ``` #### zero_shot_image_classification[[huggingface_hub.InferenceClient.zero_shot_image_classification]] ```python zero_shot_image_classification(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], candidate_labels: list, model: str | None = None, hypothesis_template: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_client.py#L3187) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 캡션할 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. candidate_labels (`list[str]`) : 이 이미지의 후보 레이블 model (`str`, *선택 사항*) : 추론에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 제공되지 않으면 기본 권장 zero-shot 이미지 분류 모델이 사용됩니다. hypothesis_template (`str`, *선택 사항*) : `candidate_labels`와 함께 사용되며, 플레이스홀더를 후보 레이블로 대체하여 이미지 분류를 시도하는 데 사용되는 문장입니다. **반환값:** `list[ZeroShotImageClassificationOutputElement]` 예측된 라벨과 그 신뢰도를 포함하는 [ZeroShotImageClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ZeroShotImageClassificationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 입력 이미지와 텍스트 라벨을 제공하여 이미지에 대한 텍스트 라벨을 예측합니다. 예: ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.zero_shot_image_classification( ... "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg", ... candidate_labels=["dog", "cat", "horse"], ... ) [ZeroShotImageClassificationOutputElement(label='dog', score=0.956),...] ``` ## 비동기 추론 클라이언트[[huggingface_hub.AsyncInferenceClient]] `asyncio`와 `httpx2`를 기반으로 한 클라이언트의 비동기 버전도 제공됩니다. #### huggingface_hub.AsyncInferenceClient[[huggingface_hub.AsyncInferenceClient]] ```python huggingface_hub.AsyncInferenceClient(model: str | None = None, provider: typing.Union[typing.Literal['baseten', 'cerebras', 'cohere', 'deepinfra', 'fal-ai', 'featherless-ai', 'fireworks-ai', 'groq', 'hf-inference', 'novita', 'nscale', 'openai', 'ovhcloud', 'publicai', 'replicate', 'scaleway', 'together', 'wavespeed', 'zai-org'], typing.Literal['auto'], NoneType] = None, token: str | None = None, timeout: float | None = None, headers: dict[str, str] | None = None, cookies: dict[str, str] | None = None, bill_to: str | None = None, base_url: str | None = None, api_key: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L112) **매개변수:** model (`str`, `optional`) : 추론을 실행할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID, 예: `meta-llama/Meta-Llama-3-8B-Instruct` 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 기본값은 None이며, 이 경우 해당 작업에 권장되는 모델이 자동으로 선택됩니다. 참고: OpenAI 클라이언트와의 호환성을 높이기 위해 `model`이 `base_url`로 별칭이 지정되었습니다. 이 두 인수는 상호 배타적입니다. 채팅 완성을 위해 `model` 또는 `base_url`로 URL이 전달되면, `(/v1)/chat/completions` 접미 경로가 URL에 추가됩니다. provider (`str`, *선택 사항*) : 추론에 사용할 프로바이더의 이름입니다. `"baseten"`, `"cerebras"`, `"cohere"`, `"deepinfra"`, `"fal-ai"`, `"featherless-ai"`, `"fireworks-ai"`, `"groq"`, `"hf-inference"`, `"novita"`, `"nscale"`, `"openai"`, `"ovhcloud"`, `"publicai"`, `"replicate"`, `"scaleway"`, `"together"`, `"wavespeed"` 또는 `"zai-org"`일 수 있습니다. 기본값은 "auto"입니다. 자동 라우팅으로, 기본적으로 "fastest" 프로바이더를 사용합니다. https://hf.co/settings/inference-providers에서 "cheapest" 또는 "preferred" 프로바이더 순서로 전환할 수 있습니다. model이 URL이거나 `base_url`이 전달되면 `provider`는 사용되지 않습니다. token (`str`, *선택 사항*) : Hugging Face 토큰. 제공되지 않으면 로컬에 저장된 토큰이 기본값으로 사용됩니다. 참고: OpenAI 클라이언트와의 호환성을 높이기 위해 `token`은 `api_key`로 별칭이 지정되었습니다. 이 두 인수는 상호 배타적이며 동작이 완전히 동일합니다. timeout (`float`, `optional`) : 서버로부터 응답을 받을 때까지 대기할 최대 초 수입니다. 기본값은 None이며, 이는 서버가 사용 가능할 때까지 루프를 돌린다는 의미입니다. headers (`dict[str, str]`, `optional`) : 서버로 보낼 추가 헤더입니다. 기본적으로 authorization 및 user-agent 헤더만 전송됩니다. 이 사전의 값은 기본 값을 덮어씁니다. bill_to (`str`, `optional`) : 요청에 사용할 청구 계정입니다. 기본적으로 요청은 사용자의 계정으로 청구됩니다. 요청은 사용자가 멤버로 가입되어 있고 Enterprise Hub에 구독한 조직에만 청구할 수 있습니다. cookies (`dict[str, str]`, `optional`) : 서버에 보낼 추가 쿠키. base_url (`str`, `optional`) : 추론을 실행할 기본 URL입니다. 이는 [InferenceClient](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient)가 `openai.OpenAI` 클라이언트와 동일한 패턴을 따르도록 `model`에서 중복된 인자입니다. `model`이 설정된 경우 사용할 수 없습니다. 기본값은 None입니다. api_key (`str`, `optional`) : 인증에 사용할 토큰. [InferenceClient](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient)가 `openai.OpenAI` 클라이언트와 동일한 패턴을 따르도록 `token`에서 중복된 인자입니다. `token`이 설정된 경우 사용할 수 없습니다. 기본값은 None입니다. 새로운 Inference Client를 초기화합니다. [InferenceClient](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient)는 추론을 수행하기 위한 통합된 경험을 제공하도록 설계되었습니다. 이 클라이언트는 (무료) Inference API, 자체 호스팅된 Inference Endpoints 또는 제3자 Inference Providers와 모두 원활하게 사용할 수 있습니다. #### audio_classification[[huggingface_hub.AsyncInferenceClient.audio_classification]] ```python audio_classification(audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, top_k: int | None = None, function_to_apply: typing.Optional[ForwardRef('AudioClassificationOutputTransform')] = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L313) **매개변수:** audio (Union[str, Path, bytes, BinaryIO]) : 분류할 오디오 콘텐츠입니다. 원시 오디오 바이트, 로컬 오디오 파일, 또는 오디오 파일을 가리키는 URL일 수 있습니다. model (`str`, *선택 사항*) : 오디오 분류에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 오디오 분류를 위한 기본 권장 모델이 사용됩니다. top_k (`int`, *선택 사항*) : 지정하면 출력을 상위 K개 가장 확률이 높은 클래스로 제한합니다. function_to_apply (`"AudioClassificationOutputTransform"`, *선택*) : 점수를 가져오기 위해 모델 출력에 적용할 함수입니다. **반환값:** `list[AudioClassificationOutputElement]` 예측된 라벨과 그 신뢰도를 포함하는 [AudioClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.AudioClassificationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 제공된 오디오 콘텐츠에 대해 오디오 분류를 수행합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.audio_classification("audio.flac") [ AudioClassificationOutputElement(score=0.4976358711719513, label='hap'), AudioClassificationOutputElement(score=0.3677836060523987, label='neu'), ... ] ``` #### audio_to_audio[[huggingface_hub.AsyncInferenceClient.audio_to_audio]] ```python audio_to_audio(audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L371) **매개변수:** audio (Union[str, Path, bytes, BinaryIO]) : 모델에 사용할 오디오 콘텐츠입니다. 원시 오디오 바이트, 로컬 오디오 파일, 또는 오디오 파일을 가리키는 URL일 수 있습니다. model (`str`, *선택 사항*) : 모델은 오디오 파일을 입력으로 받아 다른 오디오 파일을 반환하는 임의의 모델일 수 있습니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL을 사용할 수 있습니다. 제공되지 않으면 audio_to_audio에 대한 기본 권장 모델이 사용됩니다. **반환값:** `list[AudioToAudioOutputElement]` blob 형식의 오디오 콘텐츠, 콘텐츠 유형, 오디오 라벨을 포함하는 [AudioToAudioOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.AudioToAudioOutputElement) 항목의 목록입니다. **예외:** ``InferenceTimeoutError`` 또는 `HfHubHTTPError` - ``InferenceTimeoutError`` -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 모델에 따라 오디오-오디오와 관련된 여러 작업을 수행합니다(예: 음성 향상, 소스 분리). 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> audio_output = await client.audio_to_audio("audio.flac") >>> async for i, item in enumerate(audio_output): >>> with open(f"output_{i}.flac", "wb") as f: f.write(item.blob) ``` #### automatic_speech_recognition[[huggingface_hub.AsyncInferenceClient.automatic_speech_recognition]] ```python automatic_speech_recognition(audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, extra_body: dict | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L424) **매개변수:** audio (Union[str, Path, bytes, BinaryIO]) : 전사할 콘텐츠입니다. 원시 오디오 바이트, 로컬 오디오 파일, 또는 오디오 파일의 URL일 수 있습니다. model (`str`, *선택 사항*) : ASR에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL을 사용할 수 있습니다. 제공되지 않으면 ASR에 권장되는 기본 모델이 사용됩니다. extra_body (`dict`, *선택 사항*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 해당 제공자의 문서를 참조하세요. **반환값:** [AutomaticSpeechRecognitionOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.AutomaticSpeechRecognitionOutput) 전사된 텍스트와 선택적으로 타임스탬프 청크를 포함하는 항목입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 오디오 콘텐츠에 대해 자동 음성 인식(ASR 또는 오디오-텍스트 변환)을 수행합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.automatic_speech_recognition("hello_world.flac").text "hello world" ``` #### chat_completion[[huggingface_hub.AsyncInferenceClient.chat_completion]] ```python chat_completion(messages: list, model: str | None = None, stream: bool = False, frequency_penalty: float | None = None, logit_bias: list[float] | None = None, logprobs: bool | None = None, max_tokens: int | None = None, n: int | None = None, presence_penalty: float | None = None, response_format: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatText, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONSchema, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONObject, NoneType] = None, seed: int | None = None, stop: list[str] | None = None, stream_options: huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputStreamOptions | None = None, temperature: float | None = None, tool_choice: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputToolChoiceClass, ForwardRef('ChatCompletionInputToolChoiceEnum'), NoneType] = None, tool_prompt: str | None = None, tools: list[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputTool] | None = None, top_logprobs: int | None = None, top_p: float | None = None, extra_body: dict | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L552) **매개변수:** messages ([ChatCompletionInputMessage](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionInputMessage) 목록) : 역할과 콘텐츠 쌍으로 구성된 대화 기록. model (`str`, *선택 사항*) : 채팅 완성(chat-completion)에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면, 채팅 기반 텍스트 생성에 대한 기본 권장 모델이 사용됩니다. 자세한 내용은 https://huggingface.co/tasks/text-generation을 참조하세요. `model`이 모델 ID인 경우, 서버에 `model` 파라미터로 전달됩니다. 요청 페이로드에서 `model`을 설정하면서 사용자 정의 URL을 정의하려면, [InferenceClient](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient)를 초기화할 때 `base_url`을 설정해야 합니다. frequency_penalty (`float`, *선택 사항*) : 지금까지의 텍스트에서 이미 존재하는 토큰의 빈도에 따라 새로운 토큰을 페널티합니다. 범위: [-2.0, 2.0]. 기본값은 0.0입니다. logit_bias (`list[float]`, *선택 사항*) : 생성된 출력에서 특정 토큰이 나타날 확률을 조정합니다. logprobs (`bool`, *선택 사항*) : 출력 토큰의 로그 확률을 반환할지 여부입니다. true인 경우, 메시지 콘텐츠에 반환된 각 출력 토큰의 로그 확률을 반환합니다. max_tokens (`int`, *선택 사항*) : 응답에 허용되는 최대 토큰 수입니다. 기본값은 100입니다. n (`int`, *선택 사항*) : 각 프롬프트에 대해 생성할 완성본의 수. presence_penalty (`float`, *선택 사항*) : -2.0과 2.0 사이의 숫자. 양의 값은 현재까지 텍스트에 이미 등장했는지에 따라 새로운 토큰에 페널티를 부과하여, 모델이 새로운 주제에 대해 이야기할 가능성을 높입니다. response_format (`ChatCompletionInputGrammarType()`, *선택*) : 문법 제약 조건. JSONSchema 또는 정규식(regex) 중 하나여야 합니다. seed (선택 사항`int`, *optional*) : 재현 가능한 제어 흐름을 위한 시드. 기본값은 None입니다. stop (`list[str]`, *선택 사항*) : 응답의 종료를 트리거하는 최대 4개의 문자열입니다. 기본값은 None입니다. stream (`bool`, *선택 사항*) : 응답의 실시간 스트리밍을 활성화합니다. 기본값은 False입니다. stream_options ([ChatCompletionInputStreamOptions](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionInputStreamOptions), *선택*) : 스트리밍 completions에 대한 옵션입니다. temperature (`float`, *선택 사항*) : 생성의 무작위성을 제어합니다. 값이 낮을수록 덜 무작위적인 완성 결과를 보장합니다. 범위: [0, 2]. 기본값은 1.0입니다. top_logprobs (`int`, *선택 사항*) : 각 토큰 위치에서 반환할 가장 가능성이 높은 토큰의 수를 0에서 5 사이의 정수로 지정합니다. 각 토큰에는 관련 로그 확률이 포함됩니다. 이 매개변수를 사용하려면 logprobs를 true로 설정해야 합니다. top_p (`float`, *선택 사항*) : 가장 가능성이 높은 다음 단어 중 샘플링할 비율. 0과 1 사이여야 합니다. 기본값은 1.0입니다. tool_choice ([ChatCompletionInputToolChoiceClass](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionInputToolChoiceClass) 또는 `ChatCompletionInputToolChoiceEnum()`, *선택 사항*) : completion에 사용할 도구입니다. 기본값은 "auto"입니다. tool_prompt (`str`, *선택 사항*) : 도구 앞에 추가할 프롬프트입니다. tools ([ChatCompletionInputTool](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionInputTool) 목록, *선택 사항*) : 모델이 호출할 수 있는 도구의 목록입니다. 현재 도구는 함수만 지원합니다. 모델이 JSON 입력을 생성할 수 있는 함수 목록을 제공하려면 이 항목을 사용하세요. extra_body (`dict`, *선택 사항*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 해당 제공자의 문서를 참조하세요. **반환값:** [ChatCompletionOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionOutput) 또는 [ChatCompletionStreamOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionStreamOutput)의 Iterable 서버에서 반환된 생성 텍스트: - `stream=False`인 경우, 생성된 텍스트는 [ChatCompletionOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionOutput)로 반환됩니다(기본값). - `stream=True`인 경우, 생성된 텍스트가 [ChatCompletionStreamOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ChatCompletionStreamOutput)의 시퀀스로 토큰 단위로 반환됩니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 언어 모델을 사용하여 대화를 완료하는 방법입니다. > [!TIP] > `client.chat_completion` 메서드는 OpenAI 클라이언트와의 호환성을 위해 `client.chat.completions.create`로 별칭이 지정되어 있습니다. 입력과 출력은 완전히 동일하며, 두 문법 중 어느 것을 사용하더라도 동일한 결과를 얻습니다. OpenAI 호환성에 대한 자세한 내용은 [추론 가이드](https://huggingface.co/docs/huggingface_hub/guides/inference#openai-compatibility)를 참고하세요. > [!TIP] > `extra_body` 인수를 사용하여 모델에 프로바이더별 매개변수를 전달할 수 있습니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> messages = [{"role": "user", "content": "What is the capital of France?"}] >>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-8B-Instruct") >>> await 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 ) ) ``` 스트리밍을 사용한 예시: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> messages = [{"role": "user", "content": "What is the capital of France?"}] >>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-8B-Instruct") >>> async for token in await client.chat_completion(messages, max_tokens=10, stream=True): ... print(token) ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content='The', role='assistant'), index=0, finish_reason=None)], created=1710498504) ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' capital', role='assistant'), index=0, finish_reason=None)], created=1710498504) (...) ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' may', role='assistant'), index=0, finish_reason=None)], created=1710498504) ``` OpenAI 문법을 사용한 예시: ```py # Must be run in an async context # instead of `from openai import OpenAI` from huggingface_hub import AsyncInferenceClient # instead of `client = OpenAI(...)` client = AsyncInferenceClient( base_url=..., api_key=..., ) output = await 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) ``` 추가(프로바이더별) 매개변수를 사용하여 서드파티 프로바이더를 직접 사용하는 예시입니다. 사용량은 Together AI 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="together", # Use Together AI provider ... api_key="", # Pass your Together API key directly ... ) >>> client.chat_completion( ... model="meta-llama/Meta-Llama-3-8B-Instruct", ... messages=[{"role": "user", "content": "What is the capital of France?"}], ... extra_body={"safety_model": "Meta-Llama/Llama-Guard-7b"}, ... ) ``` Hugging Face Routing을 통해 서드파티 제공업체를 사용하는 예시입니다. 사용량은 Hugging Face 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="novita", # Use Novita provider ... api_key="hf_...", # Pass your HF token ... ) >>> client.chat_completion( ... model="meta-llama/Meta-Llama-3-8B-Instruct", ... messages=[{"role": "user", "content": "What is the capital of France?"}], ... ) ``` 이미지 + 텍스트를 입력으로 사용하는 예시: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient # provide a remote URL >>> image_url ="https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" # or a base64-encoded image >>> image_path = "/path/to/image.jpeg" >>> with open(image_path, "rb") as f: ... base64_image = base64.b64encode(f.read()).decode("utf-8") >>> image_url = f"data:image/jpeg;base64,{base64_image}" >>> client = AsyncInferenceClient("meta-llama/Llama-3.2-11B-Vision-Instruct") >>> output = await client.chat.completions.create( ... messages=[ ... { ... "role": "user", ... "content": [ ... { ... "type": "image_url", ... "image_url": {"url": image_url}, ... }, ... { ... "type": "text", ... "text": "Describe this image in one sentence.", ... }, ... ], ... }, ... ], ... ) >>> output The image depicts the iconic Statue of Liberty situated in New York Harbor, New York, on a clear day. ``` 도구를 사용한 예시: ```py # Must be run in an async context >>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct") >>> messages = [ ... { ... "role": "system", ... "content": "Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous.", ... }, ... { ... "role": "user", ... "content": "What's the weather like the next 3 days in San Francisco, CA?", ... }, ... ] >>> tools = [ ... { ... "type": "function", ... "function": { ... "name": "get_current_weather", ... "description": "Get the current weather", ... "parameters": { ... "type": "object", ... "properties": { ... "location": { ... "type": "string", ... "description": "The city and state, e.g. San Francisco, CA", ... }, ... "format": { ... "type": "string", ... "enum": ["celsius", "fahrenheit"], ... "description": "The temperature unit to use. Infer this from the users location.", ... }, ... }, ... "required": ["location", "format"], ... }, ... }, ... }, ... { ... "type": "function", ... "function": { ... "name": "get_n_day_weather_forecast", ... "description": "Get an N-day weather forecast", ... "parameters": { ... "type": "object", ... "properties": { ... "location": { ... "type": "string", ... "description": "The city and state, e.g. San Francisco, CA", ... }, ... "format": { ... "type": "string", ... "enum": ["celsius", "fahrenheit"], ... "description": "The temperature unit to use. Infer this from the users location.", ... }, ... "num_days": { ... "type": "integer", ... "description": "The number of days to forecast", ... }, ... }, ... "required": ["location", "format", "num_days"], ... }, ... }, ... }, ... ] >>> response = await client.chat_completion( ... model="meta-llama/Meta-Llama-3-70B-Instruct", ... messages=messages, ... tools=tools, ... tool_choice="auto", ... max_tokens=500, ... ) >>> response.choices[0].message.tool_calls[0].function ChatCompletionOutputFunctionDefinition( arguments={ 'location': 'San Francisco, CA', 'format': 'fahrenheit', 'num_days': 3 }, name='get_n_day_weather_forecast', description=None ) ``` response_format를 사용한 예시: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct") >>> messages = [ ... { ... "role": "user", ... "content": "I saw a puppy a cat and a raccoon during my bike ride in the park. What did I see and when?", ... }, ... ] >>> response_format = { ... "type": "json", ... "value": { ... "properties": { ... "location": {"type": "string"}, ... "activity": {"type": "string"}, ... "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5}, ... "animals": {"type": "array", "items": {"type": "string"}}, ... }, ... "required": ["location", "activity", "animals_seen", "animals"], ... }, ... } >>> response = await client.chat_completion( ... messages=messages, ... response_format=response_format, ... max_tokens=500, ... ) >>> response.choices[0].message.content '{ y": "bike ride", ": ["puppy", "cat", "raccoon"], _seen": 3, n": "park"}' ``` #### 닫기[[huggingface_hub.AsyncInferenceClient.close]] ```python close() ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L226) 클라이언트를 닫습니다. 이 메서드는 클라이언트를 컨텍스트 매니저로 사용할 때 자동으로 호출됩니다. #### document_question_answering[[huggingface_hub.AsyncInferenceClient.document_question_answering]] ```python document_question_answering(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], question: str, model: str | None = None, doc_stride: int | None = None, handle_impossible_answer: bool | None = None, lang: str | None = None, max_answer_len: int | None = None, max_question_len: int | None = None, max_seq_len: int | None = None, top_k: int | None = None, word_boxes: list[list[float] | str] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L960) **매개변수:** image (`Union[str, Path, bytes, BinaryIO]`) : 컨텍스트에 사용할 입력 이미지입니다. 원시 바이트, 이미지 파일, 또는 온라인 이미지의 URL일 수 있습니다. question (`str`) : 답변할 질문. model (`str`, *선택 사항*) : 문서 질의응답 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 문서 질의응답 모델이 사용됩니다. 기본값은 None입니다. doc_stride (`int`, *선택 사항*) : 문서의 단어가 모델의 질문과 함께 들어갈 수 없을 정도로 길면, 일부 중복을 포함하여 여러 청크로 나뉩니다. 이 인수는 해당 중복의 크기를 제어합니다. handle_impossible_answer (`bool`, *선택 사항*) : 불가능을 답변으로 허용할지 여부 lang (`str`, *선택 사항*) : OCR 실행 시 사용할 언어입니다. 기본값은 영어입니다. max_answer_len (`int`, *선택 사항*) : 예측된 답변의 최대 길이 (예: 이 길이보다 짧은 답변만 고려됨). max_question_len (`int`, *선택 사항*) : 토큰화 후 질문의 최대 길이입니다. 필요할 경우 잘립니다. max_seq_len (`int`, *선택 사항*) : 모델에 전달되는 각 청크의 토큰 단위로, 전체 문장(컨텍스트 + 질문)의 최대 길이입니다. 필요할 경우 doc_stride를 오버랩으로 사용하여 컨텍스트를 여러 청크로 분할합니다. top_k (`int`, *선택 사항*) : 반환할 답변의 수(가능성 순서대로 선택됩니다). 컨텍스트 내에서 사용할 수 있는 옵션이 충분하지 않으면 top_k보다 적은 답변을 반환할 수 있습니다. word_boxes (`list[Union[list[float], str`, *optional*) : 단어와 바운딩 박스(0->1000으로 정규화)의 목록입니다. 제공된 경우, 추론 과정에서 OCR 단계를 건너뛰고 제공된 바운딩 박스를 대신 사용합니다. **반환값:** `list[DocumentQuestionAnsweringOutputElement]` 예측된 라벨, 관련 확률, 단어 ID, 페이지 번호를 포함하는 [DocumentQuestionAnsweringOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.DocumentQuestionAnsweringOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 문서 이미지에 대한 질문에 답합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.document_question_answering(image="https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png", question="What is the invoice number?") [DocumentQuestionAnsweringOutputElement(answer='us-001', end=16, score=0.9999666213989258, start=16)] ``` #### feature_extraction[[huggingface_hub.AsyncInferenceClient.feature_extraction]] ```python feature_extraction(text: str | list[str], normalize: bool | None = None, prompt_name: str | None = None, truncate: bool | None = None, truncation_direction: typing.Optional[typing.Literal['left', 'right']] = None, dimensions: int | None = None, encoding_format: typing.Optional[typing.Literal['float', 'base64']] = None, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1048) **매개변수:** text (*str* 또는 *list[str]*) : 임베딩할 텍스트 또는 텍스트 목록. model (*str*, *optional*) : feature extraction 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 feature extraction 모델이 사용됩니다. 기본값은 None입니다. normalize (*bool*, *optional*) : 임베딩을 정규화할지 여부. Text-Embedding-Inference로 구동되는 서버에서만 사용할 수 있습니다. prompt_name (*str*, *optional*) : The name of the prompt that should be used by for encoding. If not set, no prompt will be applied. Must be a key in the *Sentence Transformers* configuration *prompts* dictionary. For example if `prompt_name` is "query" and the `prompts` is &lcub;"query": "query: ",...}, then the sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?" because the prompt text will be prepended before any text to encode. truncate (*bool*, *optional*) : 임베딩을 잘라낼지 여부. Text-Embedding-Inference로 구동되는 서버에서만 사용할 수 있습니다. truncation_direction (*Literal["left", "right"]*, *선택*) : *truncate=True*가 전달될 때 입력의 어느 쪽을 잘라낼지 지정합니다. dimensions (*int*, *optional*) : 결과 출력 임베딩이 가져야 할 차원의 수입니다. OpenAI 호환 임베딩 엔드포인트에서만 사용할 수 있습니다. encoding_format (*Literal["float", "base64"]*, *선택*) : 출력 임베딩의 형식입니다. "float" 또는 "base64" 중 하나입니다. OpenAI 호환 임베딩 엔드포인트에서만 사용할 수 있습니다. **반환값:** `*np.ndarray*` float32 numpy 배열로 입력 텍스트를 나타내는 임베딩. **예외:** [*InferenceTimeoutError*] 또는 [*HfHubHTTPError*] - [*InferenceTimeoutError*] -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - [*HfHubHTTPError*] -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트 또는 텍스트 배치에 대해 임베딩을 생성합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.feature_extraction("Hi, who are you?") array([[ 2.424802 , 2.93384 , 1.1750331 , ..., 1.240499, -0.13776633, -0.7889173 ], [-0.42943227, -0.6364878 , -1.693462 , ..., 0.41978157, -2.4336355 , 0.6162071 ], ..., [ 0.28552425, -0.928395 , -1.2077185 , ..., 0.76810825, -2.1069427 , 0.6236161 ]], dtype=float32) ``` #### fill_mask[[huggingface_hub.AsyncInferenceClient.fill_mask]] ```python fill_mask(text: str, model: str | None = None, targets: list[str] | None = None, top_k: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1132) **매개변수:** text (`str`) : 채울 문자열이며, [MASK] 토큰을 포함해야 합니다 (마스크의 정확한 이름은 모델 카드에서 확인하세요). model (`str`, *선택 사항*) : fill mask 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 fill mask 모델이 사용됩니다. targets (`list[str`, *optional*) : 전달되면, 모델은 전체 어휘를 검색하는 대신 전달된 대상에 점수를 제한합니다. 제공된 대상이 모델 어휘에 없으면 토큰화되고, 생성된 첫 번째 토큰이 사용됩니다(경고와 함께, 이는 더 느릴 수 있음). top_k (`int`, *선택 사항*) : 전달되면 반환할 예측의 수를 재정의합니다. **반환값:** `list[FillMaskOutputElement]` 예측된 라벨, 관련 확률, 토큰 참조, 완성된 텍스트를 포함하는 [FillMaskOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.FillMaskOutputElement) 항목의 목록 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 누락된 단어(정확히 말하면 토큰)로 빈칸을 채웁니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.fill_mask("The goal of life is .") [ FillMaskOutputElement(score=0.06897063553333282, token=11098, token_str=' happiness', sequence='The goal of life is happiness.'), FillMaskOutputElement(score=0.06554922461509705, token=45075, token_str=' immortality', sequence='The goal of life is immortality.') ] ``` #### get_endpoint_info[[huggingface_hub.AsyncInferenceClient.get_endpoint_info]] ```python get_endpoint_info(model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L3302) **매개변수:** model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. **반환값:** `dict[str, Any]` 엔드포인트에 대한 정보. 배포된 엔드포인트에 대한 정보를 가져옵니다. 이 엔드포인트는 Text-Generation-Inference(TGI) 또는 Text-Embedding-Inference(TEI)로 구동되는 엔드포인트에서만 사용할 수 있습니다. `transformers`로 구동되는 엔드포인트는 빈 페이로드를 반환합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct") >>> await client.get_endpoint_info() { 'model_id': 'meta-llama/Meta-Llama-3-70B-Instruct', 'model_sha': None, 'model_dtype': 'torch.float16', 'model_device_type': 'cuda', 'model_pipeline_tag': None, 'max_concurrent_requests': 128, 'max_best_of': 2, 'max_stop_sequences': 4, 'max_input_length': 8191, 'max_total_tokens': 8192, 'waiting_served_ratio': 0.3, 'max_batch_total_tokens': 1259392, 'max_waiting_tokens': 20, 'max_batch_size': None, 'validation_workers': 32, 'max_client_batch_size': 4, 'version': '2.0.2', 'sha': 'dccab72549635c7eb5ddb17f43f0b7cdff07c214', 'docker_label': 'sha-dccab72' } ``` #### health_check[[huggingface_hub.AsyncInferenceClient.health_check]] ```python health_check(model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L3362) **매개변수:** model (`str`, *선택 사항*) : Inference Endpoint의 URL입니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. **반환값:** `bool` 모든 것이 정상적으로 작동하는 경우 True입니다. 배포된 엔드포인트의 상태를 확인합니다. Health check은 Text-Generation-Inference(TGI) 또는 Text-Embedding-Inference(TEI) 기반의 Inference Endpoints에서만 사용할 수 있습니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient("https://jzgu0buei5.us-east-1.aws.endpoints.huggingface.cloud") >>> await client.health_check() True ``` #### image_classification[[huggingface_hub.AsyncInferenceClient.image_classification]] ```python image_classification(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, function_to_apply: typing.Optional[ForwardRef('ImageClassificationOutputTransform')] = None, top_k: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1189) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 분류할 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 이미지 분류에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 이미지 분류를 위한 기본 권장 모델이 사용됩니다. function_to_apply (`"ImageClassificationOutputTransform"`, *선택*) : 점수를 가져오기 위해 모델 출력에 적용할 함수입니다. top_k (`int`, *선택 사항*) : 지정하면 출력을 상위 K개 가장 확률이 높은 클래스로 제한합니다. **반환값:** `list[ImageClassificationOutputElement]` 예측된 라벨과 관련 확률을 포함하는 [ImageClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ImageClassificationOutputElement) 항목의 목록 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 주어진 이미지에 대해 이미지 분류를 수행합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg") [ImageClassificationOutputElement(label='Blenheim spaniel', score=0.9779096841812134), ...] ``` #### image_segmentation[[huggingface_hub.AsyncInferenceClient.image_segmentation]] ```python image_segmentation(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, mask_threshold: float | None = None, overlap_mask_area_threshold: float | None = None, subtask: typing.Optional[ForwardRef('ImageSegmentationSubtask')] = None, threshold: float | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1240) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 분할할 이미지. 원시 바이트, 이미지 파일, 온라인 이미지의 URL 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 이미지 분할에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 이미지 분할을 위한 기본 권장 모델이 사용됩니다. mask_threshold (`float`, *선택 사항*) : 예측된 마스크를 바이너리 값으로 변환할 때 사용할 임계값. overlap_mask_area_threshold (`float`, *선택 사항*) : 작고 분리된 세그먼트를 제거하기 위한 마스크 오버랩 임계값. subtask (`"ImageSegmentationSubtask"`, *선택 사항*) : 모델의 기능에 따라 수행할 분할 작업입니다. threshold (`float`, *선택 사항*) : 예측된 마스크를 필터링할 확률 임계값. **반환값:** `list[ImageSegmentationOutputElement]` 분할된 마스크와 관련 속성을 포함하는 [ImageSegmentationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ImageSegmentationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 주어진 이미지에 대해 이미지 분할을 수행합니다. > [!WARNING] > 이미지를 다루려면 `PIL`이 설치되어 있어야 합니다(`pip install Pillow`). 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.image_segmentation("cat.jpg") [ImageSegmentationOutputElement(score=0.989008, label='LABEL_184', mask=), ...] ``` #### image_to_image[[huggingface_hub.AsyncInferenceClient.image_to_image]] ```python image_to_image(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], prompt: str | None = None, negative_prompt: str | None = None, num_inference_steps: int | None = None, guidance_scale: float | None = None, model: str | None = None, target_size: huggingface_hub.inference._generated.types.image_to_image.ImageToImageTargetSize | None = None, **kwargs) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1309) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 번역을 위한 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. prompt (`str`, *선택 사항*) : 이미지 생성을 안내하는 텍스트 프롬프트입니다. negative_prompt (`str`, *선택 사항*) : 이미지 생성에서 포함하지 말아야 할 내용을 안내하는 프롬프트 하나입니다. num_inference_steps (`int`, *선택 사항*) : 확산 모델용입니다. 디노이징 단계의 수를 지정합니다. 디노이징 단계가 많을수록 일반적으로 더 높은 품질의 이미지를 생성하지만, 추론 속도는 느려집니다. guidance_scale (`float`, *선택 사항*) : 확산 모델용입니다. guidance scale 값이 높을수록 모델은 텍스트 프롬프트와 밀접하게 연결된 이미지를 생성하도록 장려되지만, 이미지 품질이 낮아지는 대가를 치릅니다. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. target_size (`ImageToImageTargetSize`, *선택 사항*) : 출력 이미지의 픽셀 단위 크기입니다. 이 매개변수는 일부 프로바이더와 특정 모델에서만 지원됩니다. 지원하지 않는 경우 무시됩니다. **반환값:** `Image` 변환된 이미지. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 이미지-이미지 변환을 수행합니다. > [!WARNING] > 이미지를 다루려면 `PIL`이 설치되어 있어야 합니다(`pip install Pillow`). 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> image = await client.image_to_image("cat.jpg", prompt="turn the cat into a tiger") >>> image.save("tiger.jpg") ``` #### image_to_text[[huggingface_hub.AsyncInferenceClient.image_to_text]] ```python image_to_text(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1466) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 캡션할 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. **반환값:** [ImageToTextOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ImageToTextOutput) 생성된 텍스트. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 입력 이미지를 받아 텍스트를 반환합니다. 모델은 사용 사례(이미지 캡셔닝, 광학 문자 인식(OCR), Pix2Struct 등)에 따라 매우 다른 출력을 생성할 수 있습니다. 모델의 고유한 특성에 대해 자세히 알아보려면 모델 카드를 확인해 보세요. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.image_to_text("cat.jpg") 'a cat standing in a grassy field ' >>> await client.image_to_text("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg") 'a dog laying on the grass next to a flower pot ' ``` #### image_to_video[[huggingface_hub.AsyncInferenceClient.image_to_video]] ```python image_to_video(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, prompt: str | None = None, negative_prompt: str | None = None, num_frames: float | None = None, num_inference_steps: int | None = None, guidance_scale: float | None = None, seed: int | None = None, target_size: huggingface_hub.inference._generated.types.image_to_video.ImageToVideoTargetSize | None = None, **kwargs) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1386) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 비디오 생성에 사용할 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. prompt (`str`, *선택 사항*) : 비디오 생성을 안내하는 텍스트 프롬프트입니다. negative_prompt (`str`, *선택 사항*) : 비디오 생성에서 포함하지 말아야 할 내용을 안내하는 프롬프트 하나입니다. num_frames (`float`, *선택 사항*) : num_frames 파라미터는 생성할 비디오 프레임 수를 결정합니다. num_inference_steps (`int`, *선택 사항*) : 확산 모델용입니다. 디노이징 단계의 수를 지정합니다. 디노이징 단계가 많을수록 일반적으로 더 높은 품질의 이미지를 생성하지만, 추론 속도는 느려집니다. guidance_scale (`float`, *선택 사항*) : 확산 모델용입니다. guidance scale 값이 높을수록 모델은 텍스트 프롬프트와 밀접하게 연결된 비디오를 생성하도록 장려되지만, 이미지 품질이 낮아지는 대가를 치릅니다. seed (`int`, *선택 사항*) : 비디오 생성에 사용할 시드입니다. target_size (`ImageToVideoTargetSize`, *선택 사항*) : 출력 비디오 프레임의 픽셀 단위 크기입니다. num_inference_steps (`int`, *선택 사항*) : 디노이징 단계 수. 디노이징 단계가 많을수록 일반적으로 더 높은 품질의 비디오를 생성하지만, 추론 속도가 느려집니다. seed (`int`, *선택 사항*) : 난수 생성기의 시드입니다. **반환값:** `bytes` 생성된 비디오. 입력 이미지에서 비디오를 생성합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> video = await client.image_to_video("cat.jpg", model="Wan-AI/Wan2.2-I2V-A14B", prompt="turn the cat into a tiger") >>> with open("tiger.mp4", "wb") as f: ... f.write(video) ``` #### object_detection[[huggingface_hub.AsyncInferenceClient.object_detection]] ```python object_detection(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], model: str | None = None, threshold: float | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1513) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 객체를 감지할 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. model (`str`, *선택 사항*) : 객체 감지에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 객체 감지를 위한 기본 권장 모델(DETR)이 사용됩니다. threshold (`float`, *선택 사항*) : 예측을 수행하는 데 필요한 확률입니다. **반환값:** `list[ObjectDetectionOutputElement]` 바운딩 박스와 관련 속성을 포함하는 [ObjectDetectionOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ObjectDetectionOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` 또는 ``ValueError`` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. - ``ValueError`` -- 요청 출력이 List가 아닌 경우. 지정된 모델을 사용하여 주어진 이미지에서 객체 감지를 수행합니다. > [!WARNING] > 이미지를 다루려면 `PIL`이 설치되어 있어야 합니다(`pip install Pillow`). 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.object_detection("people.jpg") [ObjectDetectionOutputElement(score=0.9486683011054993, label='person', box=ObjectDetectionBoundingBox(xmin=59, ymin=39, xmax=420, ymax=510)), ...] ``` #### 질문_답변[[huggingface_hub.AsyncInferenceClient.question_answering]] ```python question_answering(question: str, context: str, model: str | None = None, align_to_words: bool | None = None, doc_stride: int | None = None, handle_impossible_answer: bool | None = None, max_answer_len: int | None = None, max_question_len: int | None = None, max_seq_len: int | None = None, top_k: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1562) **매개변수:** question (`str`) : 답변할 질문. context (`str`) : 질문의 컨텍스트. model (`str`) : 질문 응답 작업에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. align_to_words (`bool`, *선택 사항*) : 답변을 실제 단어에 맞게 정렬을 시도합니다. 공백으로 구분되는 언어에서 품질을 향상시킵니다. 공백으로 구분되지 않는 언어(일본어 또는 중국어 등)에서는 품질이 저하될 수 있습니다 doc_stride (`int`, *선택 사항*) : 컨텍스트가 모델의 질문과 함께 들어갈 수 없을 정도로 너무 길면, 일부 중복을 포함하여 여러 청크로 나뉩니다. 이 인수는 해당 중복의 크기를 제어합니다. handle_impossible_answer (`bool`, *선택 사항*) : 불가능을 답변으로 허용할지 여부. max_answer_len (`int`, *선택 사항*) : 예측된 답변의 최대 길이 (예: 이 길이보다 짧은 답변만 고려됨). max_question_len (`int`, *선택 사항*) : 토큰화 후 질문의 최대 길이입니다. 필요할 경우 잘립니다. max_seq_len (`int`, *선택 사항*) : 모델에 전달되는 각 청크의 토큰 수로 측정된 전체 문장(컨텍스트 + 질문)의 최대 길이입니다. 필요할 경우 docStride를 오버랩으로 사용하여 컨텍스트를 여러 청크로 나눕니다. top_k (`int`, *선택 사항*) : 반환할 답변의 수(가능성 순서대로 선택됩니다). 컨텍스트 내에서 사용할 수 있는 옵션이 충분하지 않으면 topk보다 적은 수의 답변이 반환됩니다. **반환값:** Union[`QuestionAnsweringOutputElement`, list[QuestionAnsweringOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.QuestionAnsweringOutputElement)] top_k가 1이거나 제공되지 않으면 단일 `QuestionAnsweringOutputElement`를 반환합니다. top_k가 1보다 크면 `QuestionAnsweringOutputElement`의 목록을 반환합니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트에서 질문에 대한 답변을 검색합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.question_answering(question="What's my name?", context="My name is Clara and I live in Berkeley.") QuestionAnsweringOutputElement(answer='Clara', end=16, score=0.9326565265655518, start=11) ``` #### sentence_similarity[[huggingface_hub.AsyncInferenceClient.sentence_similarity]] ```python sentence_similarity(sentence: str, other_sentences: list, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1647) **매개변수:** sentence (`str`) : 다른 문장과 비교할 주 문장입니다. other_sentences (`list[str]`) : 비교할 문장 목록. model (`str`, *선택 사항*) : 문장 유사도 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 문장 유사도 모델이 사용됩니다. 기본값은 None입니다. **반환값:** `list[float]` 입력 텍스트를 나타내는 임베딩. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 임베딩을 비교하여 문장과 다른 문장 목록 간의 의미적 유사도를 계산합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.sentence_similarity( ... "Machine learning is so easy.", ... other_sentences=[ ... "Deep learning is so straightforward.", ... "This is so difficult, like rocket science.", ... "I can't believe how much I struggled with this.", ... ], ... ) [0.7785726189613342, 0.45876261591911316, 0.2906220555305481] ``` #### 요약[[huggingface_hub.AsyncInferenceClient.summarization]] ```python summarization(text: str, model: str | None = None, clean_up_tokenization_spaces: bool | None = None, generate_parameters: dict[str, typing.Any] | None = None, truncation: typing.Optional[ForwardRef('SummarizationTruncationStrategy')] = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1701) **매개변수:** text (`str`) : 요약할 입력 텍스트. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 요약에 권장되는 기본 모델이 사용됩니다. clean_up_tokenization_spaces (`bool`, *선택 사항*) : 텍스트 출력의 잠재적인 추가 공백을 정리할지 여부. generate_parameters (`dict[str, Any]`, *선택 사항*) : 텍스트 생성 알고리즘의 추가 매개변수 설정. truncation (`"SummarizationTruncationStrategy"`, *선택 사항*) : 사용할 절단 전략입니다. **반환값:** [SummarizationOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.SummarizationOutput) 생성된 요약 텍스트. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 주어진 텍스트의 요약을 생성합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.summarization("The Eiffel tower...") SummarizationOutput(generated_text="The Eiffel tower is one of the most famous landmarks in the world....") ``` #### table_question_answering[[huggingface_hub.AsyncInferenceClient.table_question_answering]] ```python table_question_answering(table: dict, query: str, model: str | None = None, padding: typing.Optional[ForwardRef('Padding')] = None, sequential: bool | None = None, truncation: bool | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1760) **매개변수:** table (`str`) : 항목이 헤더이고 리스트가 모든 값인 리스트의 딕셔너리로 표현된 데이터 테이블입니다. 모든 리스트는 동일한 크기를 가져야 합니다. query (`str`) : 테이블에 질문하고 싶은 일반 텍스트 쿼리입니다. model (`str`) : 테이블 질의응답 작업에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. padding (`"Padding"`, *선택*) : 패딩을 활성화하고 제어합니다. sequential (`bool`, *선택 사항*) : 추론을 순차적으로 수행할지 배치로 수행할지를 결정합니다. 배치 처리가 더 빠르지만, SQA와 같은 모델은 대화형 특성상 시퀀스 내 관계를 추출하려면 추론을 순차적으로 수행해야 합니다. truncation (`bool`, *선택 사항*) : 잘라내기(truncation)를 활성화하고 제어합니다. **반환값:** [TableQuestionAnsweringOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TableQuestionAnsweringOutputElement) 답변, 좌표, 셀 및 사용된 어그리게이터를 포함하는 테이블 질문 응답 출력 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. … 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> query = "How many stars does the transformers repository have?" >>> table = {"Repository": ["Transformers", "Datasets", "Tokenizers"], "Stars": ["36542", "4512", "3934"]} >>> await client.table_question_answering(table, query, model="google/tapas-base-finetuned-wtq") TableQuestionAnsweringOutputElement(answer='36542', coordinates=[[0, 1]], cells=['36542'], aggregator='AVERAGE') ``` #### tabular_classification[[huggingface_hub.AsyncInferenceClient.tabular_classification]] ```python tabular_classification(table: dict, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1823) **매개변수:** table (`dict[str, Any]`) : 분류할 속성의 집합. model (`str`, *선택 사항*) : 표형 분류 작업에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 표형 분류 모델이 사용됩니다. 기본값은 None입니다. **반환값:** `List` … **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. … 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> table = { ... "fixed_acidity": ["7.4", "7.8", "10.3"], ... "volatile_acidity": ["0.7", "0.88", "0.32"], ... "citric_acid": ["0", "0", "0.45"], ... "residual_sugar": ["1.9", "2.6", "6.4"], ... "chlorides": ["0.076", "0.098", "0.073"], ... "free_sulfur_dioxide": ["11", "25", "5"], ... "total_sulfur_dioxide": ["34", "67", "13"], ... "density": ["0.9978", "0.9968", "0.9976"], ... "pH": ["3.51", "3.2", "3.23"], ... "sulphates": ["0.56", "0.68", "0.82"], ... "alcohol": ["9.4", "9.8", "12.6"], ... } >>> await client.tabular_classification(table=table, model="julien-c/wine-quality") ["5", "5", "5"] ``` #### tabular_regression[[huggingface_hub.AsyncInferenceClient.tabular_regression]] ```python tabular_regression(table: dict, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1879) **매개변수:** table (`dict[str, Any]`) : 테이블에 저장된 속성의 집합입니다. 타겟을 예측하는 데 사용되는 속성은 수치형과 범주형 모두일 수 있습니다. model (`str`, *선택 사항*) : 표형 회귀 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 표형 회귀 모델이 사용됩니다. 기본값은 None입니다. **반환값:** `List` 예측된 수치형 대상 값의 목록 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 테이블의 속성/특징 집합이 주어졌을 때 수치형 대상 값을 예측하는 작업입니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> table = { ... "Height": ["11.52", "12.48", "12.3778"], ... "Length1": ["23.2", "24", "23.9"], ... "Length2": ["25.4", "26.3", "26.5"], ... "Length3": ["30", "31.2", "31.1"], ... "Species": ["Bream", "Bream", "Bream"], ... "Width": ["4.02", "4.3056", "4.6961"], ... } >>> await client.tabular_regression(table, model="scikit-learn/Fish-Weight") [110, 120, 130] ``` #### text_classification[[huggingface_hub.AsyncInferenceClient.text_classification]] ```python text_classification(text: str, model: str | None = None, top_k: int | None = None, function_to_apply: typing.Optional[ForwardRef('TextClassificationOutputTransform')] = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L1930) **매개변수:** text (`str`) : 분류할 문자열. model (`str`, *선택 사항*) : 텍스트 분류 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 텍스트 분류 모델이 사용됩니다. 기본값은 None입니다. top_k (`int`, *선택 사항*) : 지정하면 출력을 상위 K개 가장 확률이 높은 클래스로 제한합니다. function_to_apply (`"TextClassificationOutputTransform"`, *선택*) : 점수를 가져오기 위해 모델 출력에 적용할 함수입니다. **반환값:** `list[TextClassificationOutputElement]` 예측된 라벨과 관련 확률을 포함하는 [TextClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TextClassificationOutputElement) 항목의 목록 **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트에 대해 텍스트 분류(예: 감정 분석)를 수행합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.text_classification("I like you") [ TextClassificationOutputElement(label='POSITIVE', score=0.9998695850372314), TextClassificationOutputElement(label='NEGATIVE', score=0.0001304351753788069), ] ``` #### text_generation[[huggingface_hub.AsyncInferenceClient.text_generation]] ```python text_generation(prompt: str, details: bool | None = None, stream: bool | None = None, model: str | None = None, adapter_id: str | None = None, best_of: int | None = None, decoder_input_details: bool | None = None, do_sample: bool | None = None, frequency_penalty: float | None = None, grammar: huggingface_hub.inference._generated.types.text_generation.TextGenerationInputGrammarType | None = None, max_new_tokens: int | None = None, repetition_penalty: float | None = None, return_full_text: bool | None = None, seed: int | None = None, stop: list[str] | None = None, temperature: float | None = None, top_k: int | None = None, top_n_tokens: int | None = None, top_p: float | None = None, truncate: int | None = None, typical_p: float | None = None, watermark: bool | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L2134) **매개변수:** prompt (`str`) : 입력 텍스트. details (`bool`, *선택 사항*) : 기본적으로 text_generation은 문자열을 반환합니다. 토큰, 확률, 시드, 종료 이유 등 상세한 출력을 원하면 `details=True`를 전달하세요. `text-generation-inference` 백엔드로 실행되는 모델에서만 사용할 수 있습니다. stream (`bool`, *선택 사항*) : 기본적으로 text_generation은 생성된 전체 텍스트를 반환합니다. 토큰 스트림을 반환하려면 `stream=True`를 전달하세요. `text-generation-inference` 백엔드로 실행되는 모델에서만 사용할 수 있습니다. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 기본값은 None입니다. adapter_id (`str`, *선택 사항*) : Lora 어댑터 ID. best_of (`int`, *선택 사항*) : best_of개의 시퀀스를 생성하고 가장 높은 토큰 logprobs를 가진 시퀀스를 반환합니다. decoder_input_details (`bool`, *선택 사항*) : 디코더 입력 토큰의 logprobs와 id를 반환합니다. 이를 적용하려면 `details=True`도 함께 설정해야 합니다. 기본값은 `False`입니다. do_sample (`bool`, *선택 사항*) : logits 샘플링 활성화 frequency_penalty (`float`, *선택 사항*) : -2.0과 2.0 사이의 숫자. 양의 값은 텍스트에서 이미 나타난 빈도에 따라 새로운 토큰을 벌점 처리하여, 모델이 동일한 줄을 그대로 반복할 가능성을 낮춥니다. grammar ([TextGenerationInputGrammarType](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TextGenerationInputGrammarType), *선택*) : 문법 제약 조건. JSONSchema 또는 정규식(regex) 중 하나여야 합니다. max_new_tokens (`int`, *선택 사항*) : 생성할 토큰의 최대 개수. 기본값은 100입니다. repetition_penalty (`float`, *선택 사항*) : 반복 페널티를 위한 매개변수입니다. 1.0은 페널티가 없음을 의미합니다. 자세한 내용은 [이 논문](https://arxiv.org/pdf/1909.05858.pdf)을 참고하세요. return_full_text (`bool`, *선택 사항*) : 생성된 텍스트 앞에 프롬프트를 붙일지 여부 seed (`int`, *선택 사항*) : 무작위 샘플링 시드 stop (`list[str]`, *선택 사항*) : `stop`의 멤버가 생성되면 토큰 생성을 중단합니다. temperature (`float`, *선택 사항*) : logits 분포를 모듈레이션하는 데 사용되는 값입니다. top_n_tokens (`int`, *선택 사항*) : 샘플링된 토큰만 반환하는 대신, 각 생성 단계에서 가장 가능성이 높은 `top_n_tokens` 토큰에 대한 정보를 반환합니다. top_k (`int`, *optional`) : top-k-filtering을 위해 유지할 가장 높은 확률의 어휘 토큰 수. top_p (`float`, *optional`) : If set to < 1, only the smallest set of most probable tokens with probabilities that add up to `top_p` or higher are kept for generation. truncate (`int`, *optional`) : 입력 토큰을 지정된 크기로 잘라냅니다. typical_p (`float`, *선택 사항`): Typical Decoding의 질량 값. 자세한 내용은 [자연어 생성을 위한 Typical Decoding](https://arxiv.org/abs/2202.00666)을 참조하세요 watermark (`bool`, *선택 사항*) : [대형 언어 모델을 위한 워터마크](https://arxiv.org/abs/2301.10226)를 사용한 워터마킹 **반환값:** `Union[str, TextGenerationOutput, AsyncIterable[str], AsyncIterable[TextGenerationStreamOutput]]` 서버에서 반환된 생성 텍스트: - `stream=False`이고 `details=False`인 경우, 생성된 텍스트는 `str`로 반환됩니다(기본값). - `stream=True`이고 `details=False`인 경우, 생성된 텍스트가 `AsyncIterable[str]`로 토큰 단위로 반환됩니다. - `stream=False`이고 `details=True`인 경우, 생성된 텍스트는 [TextGenerationOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TextGenerationOutput)로 더 자세한 정보와 함께 반환됩니다. - `details=True`이고 `stream=True`인 경우, 생성된 텍스트는 [TextGenerationStreamOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TextGenerationStreamOutput)의 반복 가능한 객체로 토큰 단위로 반환됩니다. **예외:** ``ValidationError`` 또는 [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - ``ValidationError`` -- 입력 값이 유효하지 않은 경우. 서버에 HTTP 호출이 수행되지 않습니다. - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 이 주어지면, 다음 텍스트를 생성합니다. > [!TIP] > 채팅 메시지에서 응답을 생성하려면 [InferenceClient.chat_completion()](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion) 메서드를 사용해야 합니다. 이 메서드는 단일 텍스트 프롬프트 대신 메시지 목록을 받아들이며, 채팅 템플릿 처리를 자동으로 수행합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() # Case 1: generate text >>> await client.text_generation("The huggingface_hub library is ", max_new_tokens=12) '100% open source and built to be easy to use.' # Case 2: iterate over the generated tokens. Useful for large generation. >>> async for token in await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, stream=True): ... print(token) 100 % open source and built to be easy to use . # Case 3: get more details about the generation process. >>> await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True) TextGenerationOutput( generated_text='100% open source and built to be easy to use.', details=TextGenerationDetails( finish_reason='length', generated_tokens=12, seed=None, prefill=[ TextGenerationPrefillOutputToken(id=487, text='The', logprob=None), TextGenerationPrefillOutputToken(id=53789, text=' hugging', logprob=-13.171875), (...) TextGenerationPrefillOutputToken(id=204, text=' ', logprob=-7.0390625) ], tokens=[ TokenElement(id=1425, text='100', logprob=-1.0175781, special=False), TokenElement(id=16, text='%', logprob=-0.0463562, special=False), (...) TokenElement(id=25, text='.', logprob=-0.5703125, special=False) ], best_of_sequences=None ) ) # Case 4: iterate over the generated tokens with more details. # Last object is more complete, containing the full generated text and the finish reason. >>> async for details in await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True, stream=True): ... print(details) ... TextGenerationStreamOutput(token=TokenElement(id=1425, text='100', logprob=-1.0175781, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=16, text='%', logprob=-0.0463562, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=1314, text=' open', logprob=-1.3359375, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=3178, text=' source', logprob=-0.28100586, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=273, text=' and', logprob=-0.5961914, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=3426, text=' built', logprob=-1.9423828, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-1.4121094, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=314, text=' be', logprob=-1.5224609, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=1833, text=' easy', logprob=-2.1132812, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-0.08520508, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement(id=745, text=' use', logprob=-0.39453125, special=False), generated_text=None, details=None) TextGenerationStreamOutput(token=TokenElement( id=25, text='.', logprob=-0.5703125, special=False), generated_text='100% open source and built to be easy to use.', details=TextGenerationStreamOutputStreamDetails(finish_reason='length', generated_tokens=12, seed=None) ) # Case 5: generate constrained output using grammar >>> response = await client.text_generation( ... prompt="I saw a puppy a cat and a raccoon during my bike ride in the park", ... model="HuggingFaceH4/zephyr-orpo-141b-A35b-v0.1", ... max_new_tokens=100, ... repetition_penalty=1.3, ... grammar={ ... "type": "json", ... "value": { ... "properties": { ... "location": {"type": "string"}, ... "activity": {"type": "string"}, ... "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5}, ... "animals": {"type": "array", "items": {"type": "string"}}, ... }, ... "required": ["location", "activity", "animals_seen", "animals"], ... }, ... }, ... ) >>> json.loads(response) { "activity": "bike riding", "animals": ["puppy", "cat", "raccoon"], "animals_seen": 3, "location": "park" } ``` #### text_to_image[[huggingface_hub.AsyncInferenceClient.text_to_image]] ```python text_to_image(prompt: str, negative_prompt: str | None = None, height: int | None = None, width: int | None = None, num_inference_steps: int | None = None, guidance_scale: float | None = None, model: str | None = None, scheduler: str | None = None, seed: int | None = None, extra_body: dict[str, typing.Any] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L2462) **매개변수:** prompt (`str`) : 이미지를 생성할 프롬프트. negative_prompt (`str`, *선택 사항*) : 이미지 생성에서 포함하지 말아야 할 내용을 안내하는 프롬프트 하나입니다. height (`int`, *선택 사항*) : 출력 이미지의 픽셀 단위 높이 width (`int`, *선택 사항*) : 출력 이미지의 픽셀 단위 너비 num_inference_steps (`int`, *선택 사항*) : 디노이징 단계의 수입니다. 디노이징 단계가 많을수록 일반적으로 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 생성합니다. guidance_scale (`float`, *선택 사항*) : guidance scale 값이 높을수록 모델은 텍스트 프롬프트와 밀접하게 연결된 이미지를 생성하도록 장려하지만, 값이 너무 높으면 포화(saturation) 및 기타 아티팩트가 발생할 수 있습니다. model (`str`, *선택 사항*) : 추론에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 텍스트-이미지 모델이 사용됩니다. 기본값은 None입니다. scheduler (`str`, *선택 사항*) : 호환되는 스케줄러로 덮어씁니다. seed (`int`, *선택 사항*) : 난수 생성기의 시드입니다. extra_body (`dict[str, Any]`, *선택*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 제공자의 문서를 참조하세요. **반환값:** `Image` 생성된 이미지. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 지정된 모델을 사용하여 주어진 텍스트를 기반으로 이미지를 생성합니다. > [!WARNING] > 이미지를 다루려면 `PIL`이 설치되어 있어야 합니다(`pip install Pillow`). > [!TIP] > `extra_body` 인수를 사용하여 모델에 프로바이더별 매개변수를 전달할 수 있습니다. 예: ```py # Must be run in an async context >>> 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") >>> image = await client.text_to_image( ... "An astronaut riding a horse on the moon.", ... negative_prompt="low resolution, blurry", ... model="stabilityai/stable-diffusion-2-1", ... ) >>> image.save("better_astronaut.png") ``` 세 번째 제공업체를 직접 사용하는 예시입니다. 사용량은 fal.ai 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="fal-ai", # Use fal.ai provider ... api_key="fal-ai-api-key", # Pass your fal.ai API key ... ) >>> image = client.text_to_image( ... "A majestic lion in a fantasy forest", ... model="black-forest-labs/FLUX.1-schnell", ... ) >>> image.save("lion.png") ``` Hugging Face Routing을 통해 서드파티 제공업체를 사용하는 예시입니다. 사용량은 Hugging Face 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", # Use replicate provider ... api_key="hf_...", # Pass your HF token ... ) >>> image = client.text_to_image( ... "An astronaut riding a horse on the moon.", ... model="black-forest-labs/FLUX.1-dev", ... ) >>> image.save("astronaut.png") ``` 추가 매개변수를 사용하여 Replicate 제공자를 사용하는 예시 ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", # Use replicate provider ... api_key="hf_...", # Pass your HF token ... ) >>> image = client.text_to_image( ... "An astronaut riding a horse on the moon.", ... model="black-forest-labs/FLUX.1-schnell", ... extra_body={"output_quality": 100}, ... ) >>> image.save("astronaut.png") ``` #### text_to_speech[[huggingface_hub.AsyncInferenceClient.text_to_speech]] ```python text_to_speech(text: str, model: str | None = None, do_sample: bool | None = None, early_stopping: typing.Union[bool, ForwardRef('TextToSpeechEarlyStoppingEnum'), NoneType] = None, epsilon_cutoff: float | None = None, eta_cutoff: float | None = None, max_length: int | None = None, max_new_tokens: int | None = None, min_length: int | None = None, min_new_tokens: int | None = None, num_beam_groups: int | None = None, num_beams: int | None = None, penalty_alpha: float | None = None, temperature: float | None = None, top_k: int | None = None, top_p: float | None = None, typical_p: float | None = None, use_cache: bool | None = None, extra_body: dict[str, typing.Any] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L2700) **매개변수:** text (`str`) : 합성할 텍스트. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 텍스트-음성 변환 모델이 사용됩니다. 기본값은 None입니다. do_sample (`bool`, *선택 사항*) : 새로운 토큰을 생성할 때 탐욕적 디코딩 대신 샘플링을 사용할지 여부. early_stopping (`Union[bool, "TextToSpeechEarlyStoppingEnum"]`, *선택*) : beam 기반 방법의 종료 조건을 제어합니다. epsilon_cutoff (`float`, *선택 사항*) : 0과 1 사이의 float 값으로 설정하면, epsilon_cutoff보다 큰 조건부 확률을 가진 토큰만 샘플링됩니다. 논문에서는 모델 크기에 따라 권장 값이 3e-4에서 9e-4 범위로 제시됩니다. 자세한 내용은 [Truncation Sampling as Language Model Desmoothing](https://hf.co/papers/2210.15191)을 참조하세요. eta_cutoff (`float`, *선택 사항*) : Eta 샘플링은 로컬 전형 샘플링과 epsilon 샘플링의 하이브리드입니다. 0과 1 사이의 float 값으로 설정하면, 해당 토큰이 eta_cutoff 또는 sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits)))보다 큰 경우에만 고려됩니다. 후자의 항은 직관적으로 sqrt(eta_cutoff)으로 스케일링된 다음 토큰의 기대 확률입니다. 논문에서는 모델 크기에 따라 권장 값이 3e-4에서 2e-3 범위로 제시됩니다. 자세한 내용은 [Truncation Sampling as Language Model Desmoothing](https://hf.co/papers/2210.15191)을 참조하세요. max_length (`int`, *선택 사항*) : 입력을 포함하여 생성된 텍스트의 최대 길이(토큰 단위). max_new_tokens (`int`, *선택 사항*) : 생성할 최대 토큰 수입니다. max_length보다 우선합니다. min_length (`int`, *선택 사항*) : 입력을 포함하여 생성된 텍스트의 최소 길이(토큰 단위). min_new_tokens (`int`, *선택 사항*) : 생성할 최소 토큰 수입니다. min_length보다 우선합니다. num_beam_groups (`int`, *선택 사항*) : 서로 다른 beam 그룹 간 다양성을 보장하기 위해 num_beams를 나누는 그룹 수. 자세한 내용은 [이 논문](https://hf.co/papers/1610.02424)을 참조하세요. num_beams (`int`, *선택 사항*) : beam search에 사용할 beam의 수. penalty_alpha (`float`, *선택 사항*) : contrastive search decoding에서 모델의 신뢰도와 퇴화 페널티를 균형 있게 조절하는 값입니다. temperature (`float`, *선택 사항*) : 다음 토큰의 확률을 조절하는 데 사용되는 값. top_k (`int`, *선택 사항*) : top-k-filtering을 위해 유지할 가장 높은 확률의 어휘 토큰 수. top_p (`float`, *선택 사항*) : float < 1로 설정하면, 생성 시 확률의 합이 top_p 이상인 가장 확률이 높은 최소 토큰 집합만 유지됩니다. typical_p (`float`, *선택 사항*) : Local typicality는 이미 생성된 부분 텍스트가 주어졌을 때, 다음으로 대상 토큰을 예측하는 조건부 확률이 다음으로 무작위 토큰을 예측하는 기대 조건부 확률과 얼마나 유사한지를 측정합니다. float < 1로 설정하면, 확률의 합이 typical_p 이상인 가장 로컬적으로 전형적인 토큰의 가장 작은 집합만 생성을 위해 유지됩니다. 자세한 내용은 [이 논문](https://hf.co/papers/2202.00666)을 참조하세요. use_cache (`bool`, *선택 사항*) : 디코딩 속도를 높이기 위해 모델이 이전의 마지막 키/값 어텐션을 사용해야 하는지 여부 extra_body (`dict[str, Any]`, *선택*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 제공자의 문서를 참조하세요. **반환값:** `bytes` 생성된 오디오. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트를 발음하는 목소리의 오디오를 합성합니다. > [!TIP] > `extra_body` 인수를 사용하여 모델에 프로바이더별 매개변수를 전달할 수 있습니다. 예: ```py # Must be run in an async context >>> from pathlib import Path >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> audio = await client.text_to_speech("Hello world") >>> Path("hello_world.flac").write_bytes(audio) ``` 세 번째 제공업체를 직접 사용하는 예시입니다. 사용량은 Replicate 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", ... api_key="your-replicate-api-key", # Pass your Replicate API key directly ... ) >>> audio = client.text_to_speech( ... text="Hello world", ... model="OuteAI/OuteTTS-0.3-500M", ... ) >>> Path("hello_world.flac").write_bytes(audio) ``` Hugging Face Routing을 통해 서드파티 제공업체를 사용하는 예시입니다. 사용량은 Hugging Face 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", ... api_key="hf_...", # Pass your HF token ... ) >>> audio =client.text_to_speech( ... text="Hello world", ... model="OuteAI/OuteTTS-0.3-500M", ... ) >>> Path("hello_world.flac").write_bytes(audio) ``` 추가 매개변수를 사용하여 Replicate 제공자를 사용하는 예시 ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", # Use replicate provider ... api_key="hf_...", # Pass your HF token ... ) >>> audio = client.text_to_speech( ... "Hello, my name is Kororo, an awesome text-to-speech model.", ... model="hexgrad/Kokoro-82M", ... extra_body={"voice": "af_nicole"}, ... ) >>> Path("hello.flac").write_bytes(audio) ``` fal.ai에서 "YuE-s1-7B-anneal-en-cot"을 사용한 음악 생성 예시 ```py >>> from huggingface_hub import InferenceClient >>> lyrics = ''' ... [verse] ... In the town where I was born ... Lived a man who sailed to sea ... And he told us of his life ... In the land of submarines ... So we sailed on to the sun ... 'Til we found a sea of green ... And we lived beneath the waves ... In our yellow submarine ... [chorus] ... We all live in a yellow submarine ... Yellow submarine, yellow submarine ... We all live in a yellow submarine ... Yellow submarine, yellow submarine ... ''' >>> genres = "pavarotti-style tenor voice" >>> client = InferenceClient( ... provider="fal-ai", ... model="m-a-p/YuE-s1-7B-anneal-en-cot", ... api_key=..., ... ) >>> audio = client.text_to_speech(lyrics, extra_body={"genres": genres}) >>> with open("output.mp3", "wb") as f: ... f.write(audio) ``` #### text_to_video[[huggingface_hub.AsyncInferenceClient.text_to_video]] ```python text_to_video(prompt: str, model: str | None = None, guidance_scale: float | None = None, negative_prompt: list[str] | None = None, num_frames: float | None = None, num_inference_steps: int | None = None, seed: int | None = None, extra_body: dict[str, typing.Any] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L2603) **매개변수:** prompt (`str`) : 비디오를 생성할 프롬프트. model (`str`, *선택 사항*) : 추론에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 텍스트-비디오 모델이 사용됩니다. 기본값은 None입니다. guidance_scale (`float`, *선택 사항*) : guidance scale 값이 높을수록 모델은 텍스트 프롬프트와 밀접하게 연결된 비디오를 생성하도록 장려하지만, 값이 너무 높으면 포화(saturation) 및 기타 아티팩트가 발생할 수 있습니다. negative_prompt (`list[str]`, *선택 사항*) : 비디오 생성에서 포함하지 말아야 할 내용을 안내하는 하나 이상의 프롬프트. num_frames (`float`, *선택 사항*) : num_frames 파라미터는 생성할 비디오 프레임 수를 결정합니다. num_inference_steps (`int`, *선택 사항*) : 디노이징 단계 수. 디노이징 단계가 많을수록 일반적으로 더 높은 품질의 비디오를 생성하지만, 추론 속도가 느려집니다. seed (`int`, *선택 사항*) : 난수 생성기의 시드입니다. extra_body (`dict[str, Any]`, *선택*) : 모델에 전달할 추가 제공자별 매개변수입니다. 지원되는 매개변수에 대해서는 제공자의 문서를 참조하세요. **반환값:** `bytes` 생성된 비디오. 주어진 텍스트를 기반으로 비디오를 생성합니다. > [!TIP] > `extra_body` 인수를 사용하여 모델에 프로바이더별 매개변수를 전달할 수 있습니다. 예: 세 번째 제공업체를 직접 사용하는 예시입니다. 사용량은 fal.ai 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="fal-ai", # Using fal.ai provider ... api_key="fal-ai-api-key", # Pass your fal.ai API key ... ) >>> video = client.text_to_video( ... "A majestic lion running in a fantasy forest", ... model="tencent/HunyuanVideo", ... ) >>> with open("lion.mp4", "wb") as file: ... file.write(video) ``` Hugging Face Routing을 통해 서드파티 제공업체를 사용하는 예시입니다. 사용량은 Hugging Face 계정으로 청구됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient( ... provider="replicate", # Using replicate provider ... api_key="hf_...", # Pass your HF token ... ) >>> video = client.text_to_video( ... "A cat running in a park", ... model="genmo/mochi-1-preview", ... ) >>> with open("cat.mp4", "wb") as file: ... file.write(video) ``` #### token_classification[[huggingface_hub.AsyncInferenceClient.token_classification]] ```python token_classification(text: str, model: str | None = None, aggregation_strategy: typing.Optional[ForwardRef('TokenClassificationAggregationStrategy')] = None, ignore_labels: list[str] | None = None, stride: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L2909) **매개변수:** text (`str`) : 분류할 문자열. model (`str`, *선택 사항*) : 토큰 분류 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 토큰 분류 모델이 사용됩니다. 기본값은 None입니다. aggregation_strategy (`"TokenClassificationAggregationStrategy"`, *선택 사항*) : 모델 예측을 기반으로 토큰을 융합하는 데 사용되는 전략 ignore_labels (`list[str`, *optional*) : 무시할 레이블 목록 stride (`int`, *선택 사항*) : 입력 텍스트를 분할할 때 청크 사이에 중복되는 토큰의 수입니다. **반환값:** `list[TokenClassificationOutputElement]` 엔티티 그룹, 신뢰도 점수, 단어, 시작 및 끝 인덱스를 포함하는 [TokenClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TokenClassificationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 주어진 텍스트에 대해 토큰 분류를 수행합니다. 일반적으로 문장 분석에 사용되며, 문법적 분석 또는 텍스트에 포함된 키워드를 이해하기 위한 Named Entity Recognition(NER)에 활용됩니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica") [ TokenClassificationOutputElement( entity_group='PER', score=0.9971321225166321, word='Sarah Jessica Parker', start=11, end=31, ), TokenClassificationOutputElement( entity_group='PER', score=0.9773476123809814, word='Jessica', start=52, end=59, ) ] ``` #### 번역[[huggingface_hub.AsyncInferenceClient.translation]] ```python translation(text: str, model: str | None = None, src_lang: str | None = None, tgt_lang: str | None = None, clean_up_tokenization_spaces: bool | None = None, truncation: typing.Optional[ForwardRef('TranslationTruncationStrategy')] = None, generate_parameters: dict[str, typing.Any] | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L2985) **매개변수:** text (`str`) : 번역할 문자열. model (`str`, *선택 사항*) : 번역 작업에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 번역 모델이 사용됩니다. 기본값은 None입니다. src_lang (`str`, *선택 사항*) : 텍스트의 원본 언어입니다. 여러 언어에서 번역할 수 있는 모델의 경우 필수입니다. tgt_lang (`str`, *선택 사항*) : 번역할 대상 언어입니다. 여러 언어로 번역할 수 있는 모델의 경우 필수입니다. clean_up_tokenization_spaces (`bool`, *선택 사항*) : 텍스트 출력의 잠재적인 추가 공백을 정리할지 여부. truncation (`"TranslationTruncationStrategy"`, *선택 사항*) : 사용할 절단 전략입니다. generate_parameters (`dict[str, Any]`, *선택 사항*) : 텍스트 생성 알고리즘의 추가 매개변수 설정. **반환값:** [TranslationOutput](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.TranslationOutput) 생성된 번역된 텍스트. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` 또는 ``ValueError`` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. - ``ValueError`` -- `src_lang`와 `tgt_lang` 인수 중 하나만 제공된 경우. 한 언어의 텍스트를 다른 언어로 변환합니다. 특정 사용 사례에 가장 적합한 모델을 선택하는 방법에 대한 자세한 내용은 https://huggingface.co/tasks/translation 을 참고하세요. 원본 언어와 대상 언어는 일반적으로 모델에 따라 달라집니다. 그러나 일부 모델에서는 원본 언어와 대상 언어를 지정할 수 있습니다. 이러한 모델 중 하나를 사용하는 경우 `src_lang` 및 `tgt_lang` 인수를 사용하여 관련 정보를 전달할 수 있습니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.translation("My name is Wolfgang and I live in Berlin") 'Mein Name ist Wolfgang und ich lebe in Berlin.' >>> await client.translation("My name is Wolfgang and I live in Berlin", model="Helsinki-NLP/opus-mt-en-fr") TranslationOutput(translation_text='Je m'appelle Wolfgang et je vis à Berlin.') ``` 언어 지정: ```py >>> client.translation("My name is Sarah Jessica Parker but you can call me Jessica", model="facebook/mbart-large-50-many-to-many-mmt", src_lang="en_XX", tgt_lang="fr_XX") "Mon nom est Sarah Jessica Parker mais vous pouvez m'appeler Jessica" ``` #### visual_question_answering[[huggingface_hub.AsyncInferenceClient.visual_question_answering]] ```python visual_question_answering(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], question: str, model: str | None = None, top_k: int | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L3075) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 컨텍스트에 사용할 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. question (`str`) : 답변할 질문. model (`str`, *선택 사항*) : 시각 질의응답 작업에 사용할 모델. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 제공되지 않으면 기본 권장 시각 질의응답 모델이 사용됩니다. 기본값은 None입니다. top_k (`int`, *선택 사항*) : 반환할 답변의 수(가능성 순서대로 선택됩니다). 컨텍스트 내에서 사용할 수 있는 옵션이 충분하지 않으면 topk보다 적은 수의 답변이 반환됩니다. **반환값:** `list[VisualQuestionAnsweringOutputElement]` 예측된 라벨과 관련 확률을 포함하는 [VisualQuestionAnsweringOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.VisualQuestionAnsweringOutputElement) 항목의 목록 **예외:** ``InferenceTimeoutError`` 또는 `HfHubHTTPError` - ``InferenceTimeoutError`` -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 이미지를 기반으로 열린 질문을 답변합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.visual_question_answering( ... image="https://huggingface.co/datasets/mishig/sample_images/resolve/main/tiger.jpg", ... question="What is the animal doing?" ... ) [ VisualQuestionAnsweringOutputElement(score=0.778609573841095, answer='laying down'), VisualQuestionAnsweringOutputElement(score=0.6957435607910156, answer='sitting'), ] ``` #### zero_shot_classification[[huggingface_hub.AsyncInferenceClient.zero_shot_classification]] ```python zero_shot_classification(text: str, candidate_labels: list, multi_label: bool | None = False, hypothesis_template: str | None = None, model: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L3135) **매개변수:** text (`str`) : 분류할 입력 텍스트. candidate_labels (`list[str]`) : 텍스트를 분류할 수 있는 클래스 라벨의 집합. multi_label (`bool`, *선택 사항*) : 여러 후보 라벨이 동시에 참일 수 있는지 여부입니다. false인 경우, 각 시퀀스에 대해 라벨 가능성의 합이 1이 되도록 점수가 정규화됩니다. true인 경우, 라벨은 독립적으로 간주되며 각 후보에 대해 확률이 정규화됩니다. hypothesis_template (`str`, *선택 사항*) : `candidate_labels`와 함께 사용되며, 플레이스홀더를 후보 레이블로 대체하여 텍스트 분류를 시도하는 데 사용되는 문장입니다. model (`str`, *선택 사항*) : 추론에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 제공되지 않으면 기본 권장 zero-shot 분류 모델이 사용됩니다. **반환값:** `list[ZeroShotClassificationOutputElement]` 예측된 라벨과 그 신뢰도를 포함하는 [ZeroShotClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ZeroShotClassificationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 입력으로 텍스트와 해당 텍스트를 분류할 후보 라벨 집합을 제공합니다. `multi_label=False`인 예시: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> text = ( ... "A new model offers an explanation for how the Galilean satellites formed around the solar system's" ... "largest world. Konstantin Batygin did not set out to solve one of the solar system's most puzzling" ... " mysteries when he went for a run up a hill in Nice, France." ... ) >>> labels = ["space & cosmos", "scientific discovery", "microbiology", "robots", "archeology"] >>> await client.zero_shot_classification(text, labels) [ ZeroShotClassificationOutputElement(label='scientific discovery', score=0.7961668968200684), ZeroShotClassificationOutputElement(label='space & cosmos', score=0.18570658564567566), ZeroShotClassificationOutputElement(label='microbiology', score=0.00730885099619627), ZeroShotClassificationOutputElement(label='archeology', score=0.006258360575884581), ZeroShotClassificationOutputElement(label='robots', score=0.004559356719255447), ] >>> await client.zero_shot_classification(text, labels, multi_label=True) [ ZeroShotClassificationOutputElement(label='scientific discovery', score=0.9829297661781311), ZeroShotClassificationOutputElement(label='space & cosmos', score=0.755190908908844), ZeroShotClassificationOutputElement(label='microbiology', score=0.0005462635890580714), ZeroShotClassificationOutputElement(label='archeology', score=0.00047131875180639327), ZeroShotClassificationOutputElement(label='robots', score=0.00030448526376858354), ] ``` `multi_label=True`와 사용자 정의 `hypothesis_template`를 사용한 예시: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.zero_shot_classification( ... text="I really like our dinner and I'm very happy. I don't like the weather though.", ... candidate_labels=["positive", "negative", "pessimistic", "optimistic"], ... multi_label=True, ... hypothesis_template="This text is {} towards the weather" ... ) [ ZeroShotClassificationOutputElement(label='negative', score=0.9231801629066467), ZeroShotClassificationOutputElement(label='pessimistic', score=0.8760990500450134), ZeroShotClassificationOutputElement(label='optimistic', score=0.0008674879791215062), ZeroShotClassificationOutputElement(label='positive', score=0.0005250611575320363) ] ``` #### zero_shot_image_classification[[huggingface_hub.AsyncInferenceClient.zero_shot_image_classification]] ```python zero_shot_image_classification(image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview], candidate_labels: list, model: str | None = None, hypothesis_template: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/inference/_generated/_async_client.py#L3238) **매개변수:** image (`Union[str, Path, bytes, BinaryIO, PIL.Image.Image]`) : 캡션할 입력 이미지입니다. 원시 바이트, 이미지 파일, 온라인 이미지의 URL, 또는 PIL Image일 수 있습니다. candidate_labels (`list[str]`) : 이 이미지의 후보 레이블 model (`str`, *선택 사항*) : 추론에 사용할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID 또는 배포된 Inference Endpoint의 URL일 수 있습니다. 이 매개변수는 인스턴스 수준에서 정의된 모델을 덮어씁니다. 제공되지 않으면 기본 권장 zero-shot 이미지 분류 모델이 사용됩니다. hypothesis_template (`str`, *선택 사항*) : `candidate_labels`와 함께 사용되며, 플레이스홀더를 후보 레이블로 대체하여 이미지 분류를 시도하는 데 사용되는 문장입니다. **반환값:** `list[ZeroShotImageClassificationOutputElement]` 예측된 라벨과 그 신뢰도를 포함하는 [ZeroShotImageClassificationOutputElement](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_types#huggingface_hub.ZeroShotImageClassificationOutputElement) 항목의 목록입니다. **예외:** [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) 또는 `HfHubHTTPError` - [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/ko/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) -- 모델이 사용 불가능하거나 요청이 시간 초과된 경우. - `HfHubHTTPError` -- HTTP 503가 아닌 다른 HTTP 오류 상태 코드로 요청이 실패한 경우. 입력 이미지와 텍스트 라벨을 제공하여 이미지에 대한 텍스트 라벨을 예측합니다. 예: ```py # Must be run in an async context >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> await client.zero_shot_image_classification( ... "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg", ... candidate_labels=["dog", "cat", "horse"], ... ) [ZeroShotImageClassificationOutputElement(label='dog', score=0.956),...] ``` ## InferenceTimeoutError[[huggingface_hub.InferenceTimeoutError]] #### huggingface_hub.InferenceTimeoutError[[huggingface_hub.InferenceTimeoutError]] ```python huggingface_hub.InferenceTimeoutError(message: str) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L155) 모델을 사용할 수 없거나 요청이 시간 초과될 때 발생하는 오류입니다.