Model (모델 클래스)

[!WARNING] smolagents는 실험적인 API라 언제든 바뀔 수 있어요. 에이전트가 반환하는 결과는 API나 밑단 모델이 바뀌면서 달라질 수 있으니 유의하세요.

에이전트와 도구에 대해 더 배우려면 소개 문서를 읽어보세요. 이 페이지는 밑단 클래스들의 API 문서를 다뤄요.

모델 클래스 개요

smolagents의 모든 모델 클래스는 초기화 시점에 temperature, max_tokens, top_p 같은 추가 키워드 인자를 직접 받아요. 이 파라미터들은 밑단 모델의 completion 호출로 자동 전달되어 창의성, 응답 길이, 샘플링 전략 같은 동작을 설정할 수 있어요.

Base Model

Model 클래스는 모든 모델 구현의 기초예요. 에이전트와 함께 동작하도록 커스텀 모델이 반드시 구현해야 하는 핵심 인터페이스를 제공하죠.

ApiModel

ApiModel 클래스는 모든 API 기반 모델 구현의 기반이에요. API 특화 모델들이 상속하는 외부 API 상호작용, rate limiting(분당 요청 수 제한), 클라이언트 관리의 공통 기능을 제공해요.

TransformersModel

편의를 위해 TransformersModel을 추가했어요. 초기화 시 주어진 model_id로 로컬 transformers 파이프라인을 만들어 앞서 말한 점들을 구현해요.

from smolagents import TransformersModel

model = TransformersModel(model_id="HuggingFaceTB/SmolLM-135M-Instruct")

print(model([{"role": "user", "content": [{"type": "text", "text": "Ok!"}]}], stop_sequences=["great"]))

>>> What a

밑단 모델이 지원하는 키워드 인자(temperature, max_new_tokens, top_p 등)를 초기화 시점에 직접 넘길 수 있어요. 이 값들은 모델 completion 호출로 전달돼요.

model = TransformersModel(
    model_id="HuggingFaceTB/SmolLM-135M-Instruct",
    temperature=0.7,
    max_new_tokens=1000
)

[!TIP] transformers와 torch가 설치되어 있어야 해요. 아니면 pip install 'smolagents[transformers]'를 실행해 주세요.

InferenceClientModel

InferenceClientModel은 LLM 실행을 위해 huggingface_hub의 InferenceClient를 감싸요. 허브의 모든 Inference Provider(Cerebras, Cohere, Fal, Fireworks, HF-Inference, Hyperbolic, Nebius, Novita, Replicate, SambaNova, Together 등)를 지원해요.

requests_per_minute 인자로 분당 요청 수 rate limit을 설정할 수도 있어요.

from smolagents import InferenceClientModel

messages = [
  {"role": "user", "content": [{"type": "text", "text": "Hello, how are you?"}]}
]

model = InferenceClientModel(provider="novita", requests_per_minute=60)
print(model(messages))

>>> Of course! If you change your mind, feel free to reach out. Take care!

밑단 모델이 지원하는 키워드 인자를 초기화 시점에 넘길 수 있어요.

model = InferenceClientModel(
    provider="novita",
    requests_per_minute=60,
    temperature=0.8,
    max_tokens=500
)

LiteLLMModel

LiteLLMModel은 LiteLLM을 활용해 다양한 프로바이더의 100개가 넘는 LLM을 지원해요. 모델 초기화 시 kwargs(예: 아래의 temperature)를 넘기면 모델을 쓸 때마다 사용돼요. requests_per_minute 인자로 rate limit도 설정할 수 있어요.

from smolagents import LiteLLMModel

messages = [
  {"role": "user", "content": [{"type": "text", "text": "Hello, how are you?"}]}
]

model = LiteLLMModel(model_id="anthropic/claude-3-5-sonnet-latest", temperature=0.2, max_tokens=10, requests_per_minute=60)
print(model(messages))

LiteLLMRouterModel

LiteLLMRouterModel은 LiteLLM Router를 감싼 wrapper예요. 여러 배포에 걸친 부하 분산(load-balancing), 큐잉을 통한 중요 요청 우선 처리, 쿨다운·폴백·지수 백오프 재시도 같은 기본적인 신뢰성 조치를 구현한 고급 라우팅 전략을 활용해요.

from smolagents import LiteLLMRouterModel

messages = [
  {"role": "user", "content": [{"type": "text", "text": "Hello, how are you?"}]}
]

model = LiteLLMRouterModel(
    model_id="llama-3.3-70b",
    model_list=[
        {
            "model_name": "llama-3.3-70b",
            "litellm_params": {"model": "groq/llama-3.3-70b", "api_key": os.getenv("GROQ_API_KEY")},
        },
        {
            "model_name": "llama-3.3-70b",
            "litellm_params": {"model": "cerebras/llama-3.3-70b", "api_key": os.getenv("CEREBRAS_API_KEY")},
        },
    ],
    client_kwargs={
        "routing_strategy": "simple-shuffle",
    },
)
print(model(messages))

OpenAIModel

이 클래스는 OpenAI 서버 호환 모델을 호출할 수 있게 해줘요. api_base url을 바꿔 다른 서버를 가리킬 수도 있어요.

import os
from smolagents import OpenAIModel

model = OpenAIModel(
    model_id="gpt-4o",
    api_base="https://api.openai.com/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

밑단 모델이 지원하는 키워드 인자를 초기화 시점에 넘길 수 있어요.

model = OpenAIModel(
    model_id="gpt-4o",
    api_base="https://api.openai.com/v1",
    api_key=os.environ["OPENAI_API_KEY"],
    temperature=0.7,
    max_tokens=1000,
    top_p=0.9,
)

AzureOpenAIModel

AzureOpenAIModel은 모든 Azure OpenAI 배포에 연결할 수 있게 해줘요. 아래는 설정 예시인데, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, OPENAI_API_VERSION 환경변수를 설정했다면 azure_endpoint, api_key, api_version 인자를 생략할 수 있어요. OPENAI_API_VERSION에 AZURE_ 접두사가 없는 점에 주의하세요. 이는 밑단 openai 패키지가 설계된 방식 때문이에요.

import os

from smolagents import AzureOpenAIModel

model = AzureOpenAIModel(
    model_id = os.environ.get("AZURE_OPENAI_MODEL"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    api_version=os.environ.get("OPENAI_API_VERSION")
)

AmazonBedrockModel

AmazonBedrockModel은 Amazon Bedrock에 연결해서 사용 가능한 모델로 에이전트를 실행하게 해줘요. 아래는 설정 예시이고, 이 클래스는 커스터마이즈 옵션도 추가로 제공해요.

import os

from smolagents import AmazonBedrockModel

model = AmazonBedrockModel(
    model_id = os.environ.get("AMAZON_BEDROCK_MODEL_ID"),
)

MLXModel

MLXModel은 mlx-lm 파이프라인으로 로컬 머신에서 추론을 실행해요.

from smolagents import MLXModel

model = MLXModel(model_id="HuggingFaceTB/SmolLM-135M-Instruct")

print(model([{"role": "user", "content": "Ok!"}], stop_sequences=["great"]))

>>> What a

[!TIP] mlx-lm이 설치되어 있어야 해요. 아니면 pip install 'smolagents[mlx-lm]'를 실행해 주세요.

VLLMModel

빠른 LLM 추론과 서빙을 위해 vLLM을 쓰는 모델이에요.

from smolagents import VLLMModel

model = VLLMModel(model_id="HuggingFaceTB/SmolLM-135M-Instruct")

print(model([{"role": "user", "content": "Ok!"}], stop_sequences=["great"]))

[!TIP] vllm이 설치되어 있어야 해요. 아니면 pip install 'smolagents[vllm]'를 실행해 주세요.

커스텀 모델

에이전트를 구동하는 나만의 모델을 만들고 쓸 수 있어요.

기본 Model 클래스를 서브클래스로 만들어 모델을 만들 수 있어요. 핵심 기준은 generate 메서드를 서브클래스로 만들되 아래 두 조건을 지키는 거예요.

입력 messages로 messages 형식(List[Dict[str, str]])을 따르고, .content 속성을 가진 객체를 반환해요.
인자 stop_sequences에 전달된 시퀀스에서 생성을 멈춰요.

예를 들어 CustomModel 클래스를 만들려면 베이스 Model 클래스를 상속해서, messages 리스트를 받고 텍스트를 담은 .content 속성을 가진 객체를 반환하는 generate 메서드를 가져야 해요. generate는 언제 생성을 멈출지 알려주는 stop_sequences 인자도 받아야 해요.

from huggingface_hub import login, InferenceClient

from smolagents import Model

login("<YOUR_HUGGINGFACEHUB_API_TOKEN>")

model_id = "meta-llama/Llama-3.3-70B-Instruct"

client = InferenceClient(model=model_id)

class CustomModel(Model):
    def generate(messages, stop_sequences=["Task"]):
        response = client.chat_completion(messages, stop=stop_sequences, max_tokens=1024)
        answer = response.choices[0].message
        return answer

custom_model = CustomModel()

추가로 generate는 grammar 인자도 받을 수 있는데, constrained generation(제약 생성)으로 형식이 올바른 에이전트 출력을 강제할 수 있어요.

출처 인용

원문: smolagents - Models (reference, Hugging Face Docs)
원본 파일: huggingface/smolagents - docs/source/en/reference/models.md

Model (모델 클래스)