# Widgets

## 위젯이란 무엇인가요?

많은 모델 저장소에는 브라우저에서 누구나 추론을 직접 실행할 수 있는 위젯이 있습니다. 이러한 위젯은 [Inference Providers](https://huggingface.co/docs/inference-providers)에 의해 구동되며, 서버리스 추론 파트너의 지원을 받아 개발자에게 수백 개의 기계 학습 모델에 대한 단순화되고 통합된 접근을 제공합니다.

현재 인기 있는 모델의 예시는 다음과 같습니다:

- [DeepSeek V3](https://huggingface.co/deepseek-ai/DeepSeek-V3-0324) - 최첨단 오픈 웨이트 대화형 모델
- [Flux Kontext](https://huggingface.co/black-forest-labs/FLUX.1-Kontext-dev) - 이미지 편집을 위한 오픈 웨이트 트랜스포머 모델
- [Falconsai의 NSFW Detection](https://huggingface.co/Falconsai/nsfw_image_detection) - 이미지 콘텐츠 모더레이션
- [ResembleAI의 Chatterbox](https://huggingface.co/ResembleAI/chatterbox) - 프로덕션급 오픈소스 텍스트-음성 변환 모델.

[모델 페이지](https://huggingface.co/models?inference_provider=all&sort=trending)에서 더 많은 모델과 위젯을 탐색하거나, [Inference Playground](https://huggingface.co/playground)에서 인터랙티브로 사용해 볼 수 있습니다.

## 위젯 활성화

모델이 최소 한 개의 Inference Provider에 의해 호스팅되는 경우 위젯이 표시되며, 이를 통해 모델 추론의 최적의 성능과 신뢰성을 보장합니다. Provider는 자율적으로 배포할 모델을 선택하고 제어합니다.

표시되는 위젯의 유형(텍스트에서 이미지, 자동 음성 인식 등)은 Hub가 모든 모델에 대해 자동으로 계산하려고 하는 특수 태그인 모델의 `pipeline_tag`에서 추론됩니다. 유일한 예외는 `conversational` 위젯으로, `pipeline_tag`가 `text-generation` 또는 `image-text-to-text`인 모든 모델에 표시됩니다. 단순성을 위해 모델당 **하나의 위젯만** 노출하도록 선택했습니다.

`transformers`와 같은 일부 라이브러리의 경우, 구성 파일(`config.json`)을 기반으로 모델 유형을 자동으로 추론할 수 있습니다. 아키텍처가 유형을 결정할 수 있습니다. 예를 들어, `AutoModelForTokenClassification`는 `token-classification`에 해당합니다. 이 부분에 관심이 있다면 [이 gist](https://gist.github.com/julien-c/857ba86a6c6a895ecd90e7f7cab48046)에서 의사 코드를 확인할 수 있습니다.

대부분의 다른 사용 사례에서는 모델 태그를 사용하여 모델 작업 유형을 결정합니다. 예를 들어, [모델 카드 메타데이터](./model-cards)에 `tag: text-classification`가 있는 경우, 추론된 `pipeline_tag`는 `text-classification`가 됩니다.

**[모델 카드 메타데이터](./model-cards#model-card-metadata)에서 `pipeline_tag: xxx`를 사용하여 파이프라인 유형을 수동으로 덮어쓸 수 있습니다.** (메타데이터 GUI 편집기를 사용하여 이 작업을 수행할 수도 있습니다).

### 모델 위젯의 예시 입력을 어떻게 제어할 수 있나요?

모델 카드의 메타데이터 섹션에서 위젯 입력을 지정할 수 있습니다:

```yaml
widget:
  - text: "This new restaurant has amazing food and great service!"
    example_title: "Positive Review"
  - text: "I'm really disappointed with this product. Poor quality and overpriced."
    example_title: "Negative Review"
  - text: "The weather is nice today."
    example_title: "Neutral Statement"
```

여러 개의 예시 입력을 제공할 수 있습니다. 위젯의 예시 드롭다운 메뉴에서 `Example 1`, `Example 2` 등으로 표시됩니다. 선택적으로 `example_title`도 함께 제공할 수 있습니다.

```yaml
widget:
  - text: "Is this review positive or negative? Review: Best cast iron skillet you will ever buy."
    example_title: "Sentiment analysis"
  - text: "Barack Obama nominated Hilary Clinton as his secretary of state on Monday. He chose her because she had ..."
    example_title: "Coreference resolution"
  - text: "On a shelf, there are five books: a gray book, a red book, a purple book, a blue book, and a black book ..."
    example_title: "Logic puzzles"
  - text: "The two men running to become New York City's next mayor will face off in their first debate Wednesday night ..."
    example_title: "Reading comprehension"
```

또한, 모델 카드 메타데이터에 텍스트가 아닌 예시 입력을 지정할 수 있습니다. 모든 위젯 유형에 대한 샘플 입력 형식의 전체 목록은 [여기](./models-widgets-examples)를 참조하세요. 비전 & 오디오 위젯 유형의 경우, `text` 대신 `src`로 예시 입력을 제공하세요.

예를 들어, 자동 음성 인식 작업을 위해 사용자가 두 개의 샘플 오디오 파일 중 하나를 선택할 수 있도록 하려면:

```yaml
widget:
  - src: https://example.org/somewhere/speech_samples/sample1.flac
    example_title: Speech sample 1
  - src: https://example.org/somewhere/speech_samples/sample2.flac
    example_title: Speech sample 2
```

모델 저장소에 예제 파일을 포함할 수도 있으며, 이를 다음과 같이 사용할 수 있습니다:

```yaml
widget:
  - src: https://huggingface.co/username/model_repo/resolve/main/sample1.flac
    example_title: Custom Speech Sample 1
```

더 편리한 점은, 해당 파일이 모델 저장소에 있는 경우 저장소 내 파일명 또는 파일 경로를 그대로 사용할 수 있다는 것입니다:

```yaml
widget:
  - src: sample1.flac
    example_title: Custom Speech Sample 1
```

또는 저장소 안에 중첩되어 있는 경우:

```yaml
widget:
  - src: nested/directory/sample1.flac
```

일부 언어와 대부분의 위젯 유형에 대한 예시 입력을 [default-widget-inputs.ts 파일](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/default-widget-inputs.ts)에 제공합니다. 일부 예시가 누락된 경우, 커뮤니티에서 추가를 위한 PR을 환영합니다!

## 예시 출력

예시 입력의 확장으로, 각 위젯 예시에서 `output` 속성에 해당 모델의 출력을 선택적으로 직접 설명할 수 있습니다.

모델이 아직 Inference Providers에 의해 지원되지 않는 경우 유용하며, 이 경우에도 모델 페이지에서 모델이 어떻게 작동하는지 및 어떤 결과를 제공하는지 보여줄 수 있습니다.

예를 들어, [automatic-speech-recognition](./models-widgets-examples#automatic-speech-recognition) 모델의 경우:

```yaml
widget:
  - src: sample1.flac
    output:
      text: "Hello my name is Julien"
```

`output` 속성은 Inference Providers의 출력 형식을 나타내는 YAML 사전이어야 합니다.

텍스트를 출력하는 모델의 경우, 위의 예시를 참조하세요.

레이블을 출력하는 모델(예: [text-classification](./models-widgets-examples#text-classification) 모델)의 경우, 출력은 다음과 같은 형태여야 합니다:

```yaml
widget:
  - text: "I liked this movie"
    output:
      - label: POSITIVE
        score: 0.8
      - label: NEGATIVE
        score: 0.2
```

마지막으로, 이미지, 오디오 또는 기타 자산 유형을 출력하는 모델의 경우, 출력에는 저장소 내부의 파일 이름이나 경로 또는 원격 URL을 가리키는 `url` 속성이 포함되어야 합니다. 예를 들어, 텍스트-이미지 변환 모델의 경우:

```yaml
widget:
  - text: "picture of a futuristic tiger, artstation"
    output:
      url: images/tiger.jpg
```

Hugging Face UI에서 예시 출력을 표시할 수도 있습니다. 예를 들어, 텍스트-이미지 모델의 경우 멋진 이미지 생성 갤러리를 보여줄 수 있습니다.

## 위젯 사용 가능 여부 및 제공자 지원

모든 모델에 위젯이 제공되지는 않습니다. 위젯 사용 가능 여부는 다음 사항에 따라 달라집니다:

1. **작업 지원**: 해당 모델의 작업은 Inference Providers 네트워크의 최소 한 개의 프로바이더에 의해 지원되어야 합니다
2. **프로바이더 가용성**: 특정 모델을 서빙하는 프로바이더가 최소 하나 이상 있어야 합니다
3. **모델 구성**: 모델에는 적절한 메타데이터와 구성 파일이 있어야 합니다

지원되는 작업의 전체 목록을 보려면 [전용 문서 페이지](https://huggingface.co/docs/inference-providers/tasks/index)를 확인하세요.

모든 프로바이더 목록과 이들이 지원하는 작업은 [이 문서 페이지](https://huggingface.co/docs/inference-providers/index#partners)에서 확인할 수 있습니다.

provider 지원이 없는 모델의 경우에도 모델 카드에 [예시 출력](#example-outputs)을 사용하여 기능을 보여줄 수 있습니다.

모델 페이지에서 _Ask for provider support_를 직접 클릭하여, 커뮤니티의 관심이 충분할 경우 프로바이더가 해당 모델을 서빙하도록 장려할 수도 있습니다.

## Inference Playground를 통한 모델 탐색

애플리케이션에 모델을 통합하기 전에 [Inference Playground](https://huggingface.co/playground)를 사용하여 인터랙티브하게 테스트할 수 있습니다. 이 플레이그라운드에서는 다음을 수행할 수 있습니다:

- 커스텀 프롬프트로 다양한 [채팅 완성 모델](https://huggingface.co/models?inference_provider=all&sort=trending&other=conversational)을 테스트해 보세요
- 다른 모델 간 응답 비교
- temperature, max tokens 등 추론 매개변수를 실험해 보세요
- 구체적인 사용 사례에 가장 적합한 모델을 찾아보세요

Playground는 위젯을 구동하는 것과 동일한 Inference Providers 인프라를 사용하므로, 모델을 자체 애플리케이션에 통합할 때 유사한 성능과 기능을 기대할 수 있습니다.