첫 번째 Inference Providers 호출 만들기

첫 번째 Inference Providers 호출 만들기

이번 가이드에서는 Inference Providers로 첫 API 호출을 해 볼게요. 목표는 인프라 세팅 없이, 5분 안에 최신 오픈소스 모델을 실제로 호출해 보는 거예요.

많은 개발자가 "오픈소스 AI 모델은 배포가 복잡할 것"이라 생각하고 쓰지 않는데요, 실제로는 그렇지 않아요. 이 가이드에서 쓰는 모델은 FLUX.1-schnell이라는 텍스트→이미지 생성 모델이에요. 코드 몇 줄만으로 이미지를 만들 수 있죠.

💡 이 가이드는 Hugging Face 계정이 있다고 가정해요. 계정이 없다면 huggingface.co에서 무료로 만들 수 있어요.

Step 1: 허브에서 모델 찾기

Hugging Face Hub에 가서 "Inference Providers" 필터로 모델을 찾아보세요. 원하는 제공자(provider)를 고를 수 있어요. 이 예시에서는 fal을 쓸 거예요.

이 예시에서는 FLUX.1-schnell 모델을 사용해요. 모델 페이지로 이동해서 오른쪽의 inference 위젯을 찾아보세요.

💡 터미널에서도 같은 작업을 할 수 있어요 — 코딩 에이전트에게 시키는 것도 가능하죠. hf CLI(huggingface_hub 설치 시 함께 옴)는 같은 필터를 지원해요:

hf models ls --pipeline-tag text-to-image --warm --sort trending_score

--warm 대신 --inference-provider fal-ai를 넣으면 특정 제공자로 좁힐 수 있고, --json을 붙이면 기계가 읽기 좋은 출력을 얻어요. 전체 필터 목록은 Hub API 페이지에서 확인할 수 있어요.

Step 2: 인터랙티브 위젯으로 시험하기

코드를 쓰기 전에 모델 페이지에서 위젯을 직접 써 보세요.

브라우저에서 제공자 중 하나를 골라 모델을 바로 테스트할 수 있고, 내 프로젝트에 쓸 코드 스니펫도 복사할 수 있어요.

1. "A serene mountain landscape at sunset" 같은 프롬프트 입력
2. "Generate" 클릭
3. 몇 초 안에 모델이 이미지를 만드는 것을 확인

이 위젯은 우리가 곧 코드로 구현할 똑같은 엔드포인트를 쓰고 있어요.

⚠️ 모델을 쓰려면 Hugging Face 계정(huggingface.co 무료)과 남은 크레딧이 필요해요.

Step 3: 클릭에서 코드로

이제 이걸 파이썬으로 재현해 볼게요. 위젯에서 "View Code Snippets" 버튼을 누르면 생성된 코드 스니펫을 볼 수 있어요.

이 스니펫에는 유효한 Hugging Face User Access Token을 채워 넣어야 해요. 토큰은 설정 페이지에서 확인할 수 있어요.

토큰을 환경변수로 설정하세요:

export HF_TOKEN="your_token_here"

💡 이 줄을 .bash_profile 같은 파일에 넣어 두면 모든 터미널 환경에서 자동으로 토큰을 불러올 수 있어요.

파이썬·TypeScript 코드 스니펫은 이 환경변수에서 토큰을 읽어요.

필요한 패키지를 설치하세요:

pip install huggingface_hub

이제 코드 스니펫으로 앱에서 이미지를 생성할 수 있어요.

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    provider="auto",
    api_key=os.environ["HF_TOKEN"],
)

# output is a PIL.Image object
image = client.text_to_image(
    "Astronaut riding a horse",
    model="black-forest-labs/FLUX.1-schnell",
)

JavaScript로도 동일하게 할 수 있어요. 패키지를 설치하고:

npm install @huggingface/inference

코드 스니펫으로 이미지를 생성해 보세요.

import { InferenceClient } from "@huggingface/inference";

const client = new InferenceClient(process.env.HF_TOKEN);

const image = await client.textToImage({
    provider: "auto",
    model: "black-forest-labs/FLUX.1-schnell",
	inputs: "Astronaut riding a horse",
	parameters: { num_inference_steps: 5 },
});
/// Use the generated image (it's a Blob)

무엇이 일어난 걸까?

잘 하셨어요! 복잡한 셋업 없이 프로덕션급 AI 모델을 써 봤어요. 코드 몇 줄로 여러분은

• 강력한 텍스트→이미지 모델에 연결하고
• 텍스트에서 커스텀 이미지를 생성하고
• 결과를 로컬에 저장했어요

방금 쓴 모델은 전문 인프라 위에서 돌아가며, 스케일링·최적화·신뢰성을 자동으로 처리하고 있어요.

더 깊게: 제공자 선택 (Provider Selection)

위 코드에서 provider="auto" 파라미터를 눈치채셨을 거예요. 이게 Inference Providers의 핵심 기능인데, 어떤 인프라 제공자가 요청을 처리할지 제어하게 해 줍니다.

auto가 강력한 이유:

1. 제공자 간 전환과 각 제공자 성능 테스트가 쉬워요.
2. 한 제공자가 불가능한 상태일 때를 대비한 폴백(fallback) 메커니즘이에요.

하지만 더 구체적으로 지정하고 싶다면 제공자를 직접 고를 수도 있어요.

제공자 선택 이해하기

provider="auto"(기본값)를 쓰면 시스템이 Inference Provider 설정의 선호 순서에 따라 모델을 서빙하는 첫 번째 제공자를 자동으로 골라줘요. 이렇게 하면:

• 자동 폴백: 한 제공자가 불가능하면 시스템이 다음 걸 시도해요
• 간단한 셋업: 어떤 제공자가 모델을 지원하는지 조사할 필요가 없어요
• 최적 라우팅: 제공자 선택을 시스템이 대신 처리해 줘요

특정 제공자 지정하기

특정 요구사항이 있다면 제공자를 명시적으로 고를 수도 있어요:

import os
from huggingface_hub import InferenceClient

client = InferenceClient(api_key=os.environ["HF_TOKEN"])

# Using automatic provider selection (default)
image_auto = client.text_to_image(
    "Astronaut riding a horse",
    model="black-forest-labs/FLUX.1-schnell",
    provider="auto"  # This is the default
)

# Using a specific provider
image_fal = client.text_to_image(
    "Astronaut riding a horse", 
    model="black-forest-labs/FLUX.1-schnell",
    provider="fal-ai"  # Explicitly use Fal AI
)

# Using another specific provider
image_replicate = client.text_to_image(
    "Astronaut riding a horse",
    model="black-forest-labs/FLUX.1-schnell", 
    provider="replicate"  # Explicitly use Replicate
)

import { InferenceClient } from "@huggingface/inference";

const client = new InferenceClient(process.env.HF_TOKEN);

// Using automatic provider selection (default)
const imageAuto = await client.textToImage({
    model: "black-forest-labs/FLUX.1-schnell",
    inputs: "Astronaut riding a horse",
    provider: "auto", // This is the default
    parameters: { num_inference_steps: 5 },
});

// Using a specific provider
const imageFal = await client.textToImage({
    model: "black-forest-labs/FLUX.1-schnell",
    inputs: "Astronaut riding a horse",
    provider: "fal-ai", // Explicitly use Fal AI
    parameters: { num_inference_steps: 5 },
});

// Using another specific provider
const imageReplicate = await client.textToImage({
    model: "black-forest-labs/FLUX.1-schnell",
    inputs: "Astronaut riding a horse",
    provider: "replicate", // Explicitly use Replicate
    parameters: { num_inference_steps: 5 },
});

언제 어떤 방식을 쓸까

provider="auto"를 쓸 때:

• Inference Providers를 막 시작했을 때
• 가장 간단한 셋업과 최대 신뢰성을 원할 때
• 특정 인프라 요구사항이 없을 때
• 제공자가 불가능한 상태일 때 자동 폴백을 원할 때

특정 제공자를 쓸 때:

• 일관된 성능 특성이 필요할 때
• 특정 결제·비용 요구사항이 있을 때
• 각 제공자의 성능을 비교 테스트하고 싶을 때

다음 단계

AI 모델을 쓰는 게 얼마나 쉬운지 봤으니, 이런 궁금증이 생길 거예요:

• 그 "provider" 시스템이 뒤에서 뭘 하고 있었나?
• 결제는 어떻게 동작하나?
• 어떤 다른 모델을 쓸 수 있나?

다음 가이드로 넘어가서 제공자 생태계를 이해하고, 인증과 결제에 대한 올바른 선택을 해 보세요.

더 알아보기 (Learn more)

• Inference Providers 개요

출처: 공식문서