Understanding the Channel-Endpoint-Model-Category Hierarchy in Bella OpenAPI Routing

The Channel-Endpoint-Model-Category hierarchy is a four-level routing structure in Bella OpenAPI that maps AI requests to concrete provider channels through either model-based or endpoint-based resolution paths, enabling intelligent load balancing and provider selection.

The Bella OpenAPI project (lianjiatech/bella-openapi) implements a sophisticated routing system to direct AI model requests to appropriate provider channels. This system relies on a four-level hierarchy—Category, Endpoint, Model, and Channel—that decouples business logic from infrastructure concerns while enabling granular traffic management and failover capabilities.

The Four Levels of the Hierarchy

The hierarchy is not a strict parent-child chain. Instead, it provides flexible linkage patterns where an endpoint can be served either by a model-based channel or by a channel bound directly to the endpoint.

• Category: Business-level grouping stored in CategoryDB and represented by EndpointCategoryTree in api/sdk/src/main/java/com/ke/bella/openapi/metadata/. Categories organize endpoints into navigable trees but do not participate in runtime routing decisions.

• Endpoint: Capability points such as /v1/chat/completions defined in EndpointDB. Endpoints link downward to Models (via model-endpoint relations) and directly to Channels (via endpoint-channel relations).

• Model: AI model definitions (e.g., gpt-4) stored in ModelDB. Models map to terminal models via linkedTo fields and connect to Channels through model-channel relations.

• Channel: Concrete provider instances (e.g., OpenAI GPT-4 channel) stored in ChannelDB. Channels hold routing attributes including priority, visibility, dataDestination, and protocol that determine selection eligibility.

How the Hierarchy Powers Request Routing

The ChannelRouter Decision Flow

In api/server/src/main/java/com/ke/bella/openapi/protocol/ChannelRouter.java, the route() method (lines 46-81) implements the core selection algorithm that traverses the hierarchy:

1. Entity Resolution: If a model parameter is provided, the router resolves the terminal model name (following linkedTo chains). Otherwise, it targets the endpoint directly.

2. Channel Retrieval: The router calls ChannelService.listActives() (lines 77-82 in api/server/src/main/java/com/ke/bella/openapi/service/ChannelService.java) to fetch active channels for either the model (EntityConstants.MODEL) or the endpoint (EntityConstants.ENDPOINT).

3. Filtering: Channels are filtered by safety level, visibility, rate limits, and availability via the filter() method.

4. Priority Selection: The pickMaxPriority() method isolates the highest-priority channels, with random() selecting one when multiple channels share the same priority level.

Model vs. Endpoint Resolution Paths

The hierarchy supports dual resolution strategies:

• Model-based routing: When a request specifies a model (e.g., gpt-4), ModelService.fetchTerminalModelName() resolves any model aliases (as implemented in api/server/src/main/java/com/ke/bella/openapi/service/ModelService.java), then selects channels bound to that terminal model.

• Endpoint-based routing: When no model is specified, the router selects channels bound directly to the requested endpoint via the endpoint-channel relation.

This flexibility allows Bella OpenAPI to support both model-agnostic endpoints and specific model requirements through the same unified interface.

Category Management and Endpoint Organization

While Categories do not influence runtime routing, they provide essential business logic grouping. The CategoryService.listTree() method (lines 48-60 in api/server/src/main/java/com/ke/bella/openapi/service/CategoryService.java) builds the category-endpoint tree for UI navigation and permission management. The EndpointCategoryTree DTO presents this hierarchy to management interfaces, enabling administrators to organize capability points logically without affecting the routing engine.

Practical Implementation Example

Below is a minimal snippet demonstrating client-side channel resolution using the Bella OpenAPI hierarchy:

// Assume we have an authenticated ApikeyInfo object (from security layer)
String endpoint = "/v1/chat/completions";
String model    = "gpt-4";               // optional; may be null

ChannelRouter router = BellaContext.getBean(ChannelRouter.class);
ChannelDB channel = router.route(endpoint, model, apikeyInfo, false);

// The returned ChannelDB contains everything needed to invoke the provider
System.out.println("Selected channel: " + channel.getChannelCode());
System.out.println("Protocol: " + channel.getProtocol());
System.out.println("PriceInfo: " + channel.getPriceInfo());

If the caller only knows the endpoint, the router automatically falls back to endpoint-bound channels. When a model is specified, the router resolves the terminal model via ModelService.fetchTerminalModelName(), then selects the best model-bound channel according to the hierarchy rules.

Summary

• The Channel-Endpoint-Model-Category hierarchy provides a four-level abstraction for routing AI requests in Bella OpenAPI, separating business organization from infrastructure concerns.
• Categories organize endpoints for UI management but do not participate in runtime routing decisions.
• Routing occurs through either model-based resolution (via linkedTo terminal models) or direct endpoint-channel binding, implemented in ChannelRouter.java.
• The ChannelRouter.route() method (lines 46-81) implements the selection logic, filtering by safety, visibility, and priority before randomly selecting among equal candidates.
• Concrete provider channels (ChannelDB) encapsulate protocol details, pricing, and routing attributes required for request fulfillment.

Frequently Asked Questions

What is the difference between model-based and endpoint-based routing?

Model-based routing resolves the terminal model name (following linkedTo chains) and selects channels bound to that specific model via model-channel relations. Endpoint-based routing selects channels bound directly to the requested capability point via endpoint-channel relations. The ChannelRouter automatically chooses the appropriate path based on whether the request includes a model parameter.

How does the Category level influence request routing?

The Category level does not participate in runtime routing decisions. According to the source code in CategoryService.java, categories exist solely for business-level grouping and UI tree construction (listTree() method, lines 48-60). They provide logical organization for endpoint management and permission checks but are never referenced by ChannelRouter during channel selection.

What happens when multiple channels have the same priority?

When multiple channels share the highest priority value after filtering, the pickMaxPriority() method returns all candidates with that priority level. The ChannelRouter then applies random() selection among these tied channels to distribute load evenly. This implementation ensures high availability while respecting priority tiers defined in ChannelDB.priority fields.

How is the terminal model resolved in the hierarchy?

Terminal model resolution occurs in ModelService when the router encounters a model alias. The system follows the linkedTo field chain in ModelDB records until reaching a model with no further linkage. This terminal model name becomes the entity code used for ChannelService.listActives(EntityConstants.MODEL, terminal) lookups, ensuring requests route to channels capable of serving the concrete model implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}