Wrappers

Reference information for the language model Wrappers API.

eva.language.models.wrappers.HuggingFaceTextModel

Bases: BaseModel[List[str], List[str]]

Wrapper class for loading HuggingFace transformers models using pipelines.

Parameters:

Name	Type	Description	Default
model_name_or_path	str	The model name or path to load the model from. This can be a local path or a model name from the HuggingFace model hub.	required
task	Literal['text-generation']	The pipeline task. Defaults to "text-generation".	'text-generation'
model_kwargs	Dict[str, Any] | None	Additional arguments for configuring the pipeline.	None
generation_kwargs	Dict[str, Any] | None	Additional generation parameters (temperature, max_length, etc.).	None

Source code in src/eva/language/models/wrappers/huggingface.py

def __init__(
    self,
    model_name_or_path: str,
    task: Literal["text-generation"] = "text-generation",
    model_kwargs: Dict[str, Any] | None = None,
    generation_kwargs: Dict[str, Any] | None = None,
) -> None:
    """Initializes the model.

    Args:
        model_name_or_path: The model name or path to load the model from.
            This can be a local path or a model name from the `HuggingFace`
            model hub.
        task: The pipeline task. Defaults to "text-generation".
        model_kwargs: Additional arguments for configuring the pipeline.
        generation_kwargs: Additional generation parameters (temperature, max_length, etc.).
    """
    super().__init__()

    self._model_name_or_path = model_name_or_path
    self._task = task
    self._model_kwargs = model_kwargs or {}
    self._generation_kwargs = generation_kwargs or {}

    self.load_model()

load_model

Loads the model as a Hugging Face pipeline.

Source code in src/eva/language/models/wrappers/huggingface.py

@override
def load_model(self) -> None:
    """Loads the model as a Hugging Face pipeline."""
    self._pipeline = pipeline(
        task=self._task,
        model=self._model_name_or_path,
        trust_remote_code=True,
        **self._model_kwargs,
    )

model_forward

Generates text using the pipeline.

Parameters:

Name	Type	Description	Default
prompts	List[str]	The input prompts for the model.	required

Returns:

Type	Description
List[str]	The generated text as a string.

Source code in src/eva/language/models/wrappers/huggingface.py

@override
def model_forward(self, prompts: List[str]) -> List[str]:
    """Generates text using the pipeline.

    Args:
        prompts: The input prompts for the model.

    Returns:
        The generated text as a string.
    """
    outputs = self._pipeline(prompts, return_full_text=False, **self._generation_kwargs)
    if outputs is None:
        raise ValueError("Outputs from the model are None.")
    results = []
    for output in outputs:
        if isinstance(output, list):
            results.append(output[0]["generated_text"])  # type: ignore
        else:
            results.append(output["generated_text"])  # type: ignore
    return results

eva.language.models.wrappers.LiteLLMTextModel

Bases: BaseModel[List[str], List[str]]

Wrapper class for using litellm for chat-based text generation.

This wrapper uses litellm's completion function which accepts a list of message dicts. The forward method converts a string prompt into a chat message with a default "user" role, optionally prepends a system message, and includes an API key if provided.

Parameters:

Name	Type	Description	Default
model_name_or_path	str	The model identifier (or name) for litellm (e.g.,"openai/gpt-4o" or "anthropic/claude-3-sonnet-20240229").	required
model_kwargs	Dict[str, Any] | None	Additional keyword arguments to pass during generation (e.g., temperature, max_tokens).	None

Source code in src/eva/language/models/wrappers/litellm.py

def __init__(
    self,
    model_name_or_path: str,
    model_kwargs: Dict[str, Any] | None = None,
) -> None:
    """Initializes the litellm chat model wrapper.

    Args:
        model_name_or_path: The model identifier (or name) for litellm
            (e.g.,"openai/gpt-4o" or "anthropic/claude-3-sonnet-20240229").
        model_kwargs: Additional keyword arguments to pass during
            generation (e.g., `temperature`, `max_tokens`).
    """
    super().__init__()
    self._model_name_or_path = model_name_or_path
    self._model_kwargs = model_kwargs or {}
    self.load_model()

load_model

Prepares the litellm model.

Note

litellm doesn't require an explicit loading step; models are called directly during generation. This method exists for API consistency.

Source code in src/eva/language/models/wrappers/litellm.py

@override
def load_model(self) -> None:
    """Prepares the litellm model.

    Note:
        litellm doesn't require an explicit loading step; models are called
        directly during generation. This method exists for API consistency.
    """
    pass

model_forward

Generates text using litellm.

Parameters:

Name	Type	Description	Default
prompts	List[str]	A list of prompts to be converted into a "user" message.	required

Returns:

Type	Description
List[str]	A list of generated text responses. Failed generations will contain
List[str]	error messages instead of generated text.

Source code in src/eva/language/models/wrappers/litellm.py

@override
def model_forward(self, prompts: List[str]) -> List[str]:
    """Generates text using litellm.

    Args:
        prompts: A list of prompts to be converted into a "user" message.

    Returns:
        A list of generated text responses. Failed generations will contain
        error messages instead of generated text.
    """
    messages = [[{"role": "user", "content": prompt}] for prompt in prompts]

    responses = batch_completion(
        model=self._model_name_or_path,
        messages=messages,
        **self._model_kwargs,
    )

    results = []
    for i, response in enumerate(responses):
        if isinstance(response, Exception):
            error_msg = f"Error generating text for prompt {i}: {response}"
            logger.error(error_msg)
            raise RuntimeError(error_msg)
        else:
            results.append(response["choices"][0]["message"]["content"])

    return results

eva.language.models.wrappers.VLLMTextModel

Bases: BaseModel

Wrapper class for using vLLM for text generation.

This wrapper loads a vLLM model, sets up the tokenizer and sampling parameters, and uses a chat template to convert a plain string prompt into the proper input format for vLLM generation. It then returns the generated text response.

Parameters:

Name	Type	Description	Default
model_name_or_path	str	The model identifier (e.g., a Hugging Face repo ID or local path).	required
model_kwargs	Dict[str, Any] | None	Arguments required to initialize the vLLM model, see link for more information.	None
generation_kwargs	Dict[str, Any] | None	Arguments required to generate the output, need to align with the arguments of vllm.SamplingParams.	None

Source code in src/eva/language/models/wrappers/vllm.py

def __init__(
    self,
    model_name_or_path: str,
    model_kwargs: Dict[str, Any] | None = None,
    generation_kwargs: Dict[str, Any] | None = None,
) -> None:
    """Initializes the vLLM model wrapper.

    Args:
        model_name_or_path: The model identifier (e.g., a Hugging Face
         repo ID or local path).
        model_kwargs: Arguments required to initialize the vLLM model,
            see [link](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/llm.py)
            for more information.
        generation_kwargs: Arguments required to generate the output,
            need to align with the arguments of
            [vllm.SamplingParams](https://github.com/vllm-project/vllm/blob/main/vllm/sampling_params.py).

    """
    super().__init__()
    self._model_name_or_path = model_name_or_path
    self._model_kwargs = model_kwargs or {}
    self._generation_kwargs = generation_kwargs or {}

    # Postpone heavy LLM initialisation to avoid pickling issues
    self._llm_model: LLM | None = None
    self._llm_tokenizer: AnyTokenizer | None = None

load_model

Create the vLLM engine on first use.

This lazy initialisation keeps the wrapper picklable by Ray / Lightning.

Source code in src/eva/language/models/wrappers/vllm.py

@override
def load_model(self) -> None:
    """Create the vLLM engine on first use.

    This lazy initialisation keeps the wrapper picklable by Ray / Lightning.
    """
    if self._llm_model is not None:
        return
    self._llm_model = LLM(model=self._model_name_or_path, **self._model_kwargs)
    if self._llm_model is None:
        raise RuntimeError("Model not initialized")
    self._llm_tokenizer = self._llm_model.get_tokenizer()

generate

Generates text for the given prompt using the vLLM model.

Parameters:

Name	Type	Description	Default
prompts	List[str]	A list of string prompts for generation.	required

Returns:

Type	Description
List[str]	The generated text response.

Source code in src/eva/language/models/wrappers/vllm.py

def generate(self, prompts: List[str]) -> List[str]:
    """Generates text for the given prompt using the vLLM model.

    Args:
        prompts: A list of string prompts for generation.

    Returns:
        The generated text response.
    """
    self.load_model()
    if self._llm_model is None:
        raise RuntimeError("Model not initialized")

    prompt_tokens = self._apply_chat_template(prompts)
    outputs = self._llm_model.generate(prompt_tokens, SamplingParams(**self._generation_kwargs))
    return [output.outputs[0].text for output in outputs]