Bella OpenAPI

The ApiKey permission system determines access based on a triplet: (caller identity, relationship between caller and target AK, operation type).

Instead of scattered logic, permissions are centralized in a permission matrix. The core mechanism uses a single entry point, checkPermission(targetCode, operation), where business logic only needs to specify the operation type.

Core Abstractions

• AkOperation: The specific action being performed (e.g., QUERY, RESET, UPDATE_QUOTA).
• AkRelation: The relationship between the caller and the target AK (OWNER, MANAGER, SAME_ORG, or UNRELATED).
• rolecode: Defines the administrative level and path permissions:
  • all: Super administrator (/**).
  • console: Console administrator (/v*/**, /console/**).
  • high: High-level personal AK.
  • low: Basic personal AK.
• ownerType: The ownership category of the AK (system, org, person, or console).

// Example of the core operation types used in permission checks
public enum AkOperation {
    QUERY,                 // Query AK info
    RESET,                 // Reset keys
    RENAME,                // Rename AK
    UPDATE_ROLE,           // Modify role/path permissions (Admin only)
    UPDATE_MANAGER,        // Modify manager (Owner/Manager can do this)
    CERTIFY,               // Security certification
    UPDATE_QUOTA,          // Modify quota
    UPDATE_QPS,            // Modify QPS limits
    CHANGE_STATUS,         // Enable/Disable
    CREATE_CHILD,          // Create child AK
    TRANSFER,              // Transfer ownership (Owner only)
    VIEW_TRANSFER_HISTORY, // Query transfer history
    BIND_SERVICE           // Bind service
}

Bella OpenAPI implements a normalization logic to handle model name format discrepancies between external systems (like Hermes) and the internal database. Specifically, it allows underscore-separated version numbers (e.g., claude_opus_4_7) to match dot-separated names in the database (e.g., claude_opus_4.7).

Key Logic: "Search-then-Replace" (先查后替)

To prevent side effects and performance degradation, the system follows a strict fallback strategy:

1. Initial Search: The system first attempts to find the model using the original model_name provided in the request.
2. Normalization Fallback: If (and only if) the original name is not found, the system applies a regex transformation to replace underscores between digits (\d_\d) with dots (\d.\d).
3. Secondary Search: The system then attempts to find the model using this new normalized name. If the normalized name exists in the model registry, it is returned.
4. Final Fallback: If the normalized name also fails, the original name is returned.

Constraints and Behavior

• Regex Precision: The transformation only targets underscores between digits (e.g., model_1_2 becomes model_1.2). Underscores in other contexts (e.g., my_custom_model) are ignored.
• No Data Mutation: The normalization happens only at the parsing layer; the original request body remains unchanged.
• Caching: The system uses JetCache (L1/L2). When a fallback occurs, the result (the normalized name) is cached under the original requested key, ensuring subsequent identical requests do not trigger the fallback logic again.

// Conceptual logic flow in ModelService.java
public String fetchTerminalModelName(String modelName) {
    // 1. Try original name
    List<String> path = getPath(modelName);
    if (!CollectionUtils.isEmpty(path)) {
        return path.get(path.size() - 1);
    }

    // 2. Fallback to normalized name
    String normalized = tryNormalizeModelName(modelName);
    if (!normalized.equals(modelName)) {
        path = getPath(normalized);
        if (!CollectionUtils.isEmpty(path)) {
            return path.get(path.size() - 1);
        }
    }
    return modelName;
}

The CapacityCalculator determines the remaining processing capability of a channel using a multi-layered strategy. It combines historical 429 error data, real-time concurrency, and completed RPM (Requests Per Minute).

Capacity Calculation Formula

Remaining Capacity = 1.0 - (Current Load / Total Capacity)

Where:

• Current Load = Current Concurrent Requests + Current Completed RPM
• Total Capacity is determined by a three-level fallback strategy:
  1. Level 1 (Most Accurate): EMA (Exponential Moving Average) fit based on historical 429 data.
  2. Level 2 (Conservative): 70% of the historical maximum RPM.
  3. Level 3 (Fallback): Fully open (100% capacity) used during cold starts or data anomalies.

Data Sources and Storage

• Historical 429 Metrics: Stored in Redis at bella-openapi-channel-metrics:{channelCode}:rpm_429_history. Format: {timestamp, rpm, avg_response_time}.
• Real-time Completed RPM: bella-openapi-channel-metrics:{channelCode}:total.completed.
• Current Concurrency: bella-openapi-channel-concurrent:{entityCode}.
• Concurrency Tracking: Managed via a modified concurrent.lua script tracking both API Key (bella-openapi-limiter-concurrent:{entityCode}:{akCode}) and Channel (bella-openapi-channel-concurrent:{entityCode}) dimensions.