Implementation:BerriAI Litellm Tag Based Routing

Attribute	Value
Sources	litellm/router_strategy/tag_based_routing.py
Domains	Router, Strategy, Tag Filtering, Team Routing
last_updated	2026-02-15 16:00 GMT

Overview

The Tag Based Routing module filters healthy deployments based on tags in request metadata, enabling team-based or feature-based routing of LLM requests.

Description

This module provides functions for tag-based deployment filtering. When enable_tag_filtering is enabled on the router, the get_deployments_for_tag function matches request tags (from metadata) against deployment tags (from litellm_params). Tag matching supports two modes controlled by tag_filtering_match_any: "match any" (default, intersection-based) where any overlap between request and deployment tags qualifies, or "match all" where request tags must be a subset of deployment tags. Deployments tagged with "default" serve as fallbacks when no specific tag match is found. For untagged requests, the system returns default-tagged deployments if available, otherwise all healthy deployments.

Usage

Import get_deployments_for_tag when implementing tag-based routing in the LiteLLM Router. Enable with enable_tag_filtering=True on the router instance.

Code Reference

Source Location

litellm/router_strategy/tag_based_routing.py

Functions

Function	Signature	Description
is_valid_deployment_tag	def is_valid_deployment_tag(deployment_tags: List[str], request_tags: List[str], match_any: bool = True) -> bool	Checks if a deployment's tags match request tags using intersection or subset logic
get_deployments_for_tag	async def get_deployments_for_tag(llm_router_instance, model: str, healthy_deployments, request_kwargs=None, metadata_variable_name="metadata")	Filters deployments by tags from request metadata; returns matching, default, or all deployments
_get_tags_from_request_kwargs	def _get_tags_from_request_kwargs(request_kwargs=None, metadata_variable_name="metadata") -> List[str]	Extracts tags from request kwargs metadata

Import

from litellm.router_strategy.tag_based_routing import get_deployments_for_tag, is_valid_deployment_tag

I/O Contract

Inputs (get_deployments_for_tag)

Parameter	Type	Description
llm_router_instance	LitellmRouter	Router instance with enable_tag_filtering and tag_filtering_match_any attributes
model	str	Model name (used in error messages)
healthy_deployments	Union[List[Any], Dict[Any, Any]]	List of healthy deployment dictionaries
request_kwargs	Optional[Dict[Any, Any]]	Request keyword arguments containing metadata with tags
metadata_variable_name	Literal["metadata", "litellm_metadata"]	Key name for metadata in request_kwargs (default: "metadata")

Outputs

Return Type	Description
list	Filtered list of deployments matching the request tags, or default deployments, or all healthy deployments
Raises ValueError	When tag filtering is enabled, request has tags, but no deployments match and no defaults exist

Usage Examples

from litellm.router_strategy.tag_based_routing import get_deployments_for_tag

# Filter deployments by tags in request metadata
filtered = await get_deployments_for_tag(
    llm_router_instance=router,
    model="gpt-4",
    healthy_deployments=[
        {
            "litellm_params": {"model": "gpt-4", "tags": ["free", "default"]},
            "model_info": {"id": "deploy-1"},
        },
        {
            "litellm_params": {"model": "gpt-4", "tags": ["premium"]},
            "model_info": {"id": "deploy-2"},
        },
    ],
    request_kwargs={"metadata": {"tags": ["premium"]}},
)
# Returns only deploy-2 (matches "premium" tag)

Related Pages

• BerriAI_Litellm_Simple_Shuffle_Strategy - Random deployment selection applied after tag filtering
• BerriAI_Litellm_Lowest_TPM_RPM_V2_Strategy - Usage-based selection applied after tag filtering
• BerriAI_Litellm_Pattern_Match_Deployments - Wildcard/regex-based deployment matching