Routing Rules Configuration¶

Doc Version: 1.0.0 Last Updated: 2026-08-23 Git Commit: f8a2eebe Author: Lincoln

Overview¶

JAiRouter provides a rule engine (v2.8.5) that enables conditional routing rules configured via the Web console or YAML. Route requests flexibly by model name, request headers, client IP, and more — without writing code.

The rule engine evaluates on every request: rules are matched by priority (highest first) and the first hit takes effect. When no rule matches, the original routing logic runs unchanged — behavior is identical to a deployment without the rule engine.

Use Cases¶

Matching Semantics¶

Condition Combination¶

• AND within a rule: all conditions must match
• OR across rules: matched by priority descending, first match wins

Rule Fields¶

Condition Types (type)¶

Operators (operator)¶

WEIGHT condition: stable hash of (clientIp + "|" + modelName), hit when hash % 100 < weight. The same (IP, model) request always yields the same result, suitable for percentage-based splits. weight comes from the condition's weight field, falling back to value, then 50.

Action Types (action.type)¶

LB_STRATEGY values: random / round-robin / least-connections / ip-hash / consistent-hash. Unknown strategies fall back to the configured one.

Web Console Configuration¶

1. Log in to the JAiRouter admin console
2. Click Configuration → Routing Rules in the left menu

Creating a Rule¶

Click 「New Rule」 and fill in the form:

Managing Rules¶

• Enable/Disable: the table switch takes effect immediately
• Priority: edit the rule to change priority (batch reorder via API)
• Edit/Delete: via the action column

Rule changes take effect immediately — no restart required.

YAML Configuration¶

Edit src/main/resources/config/router/rules.yml:

model:
  rules:
    - id: route-vllm-header
      name: Route to vLLM adapter by header
      enabled: true
      priority: 100
      conditions:
        - type: HEADER
          field: x-routing
          operator: EQUALS
          value: vllm
      action:
        type: TARGET_ADAPTER
        adapter-name: vllm

    - id: route-internal-ip
      name: Pin internal IPs to dedicated instance
      enabled: true
      priority: 90
      conditions:
        - type: CLIENT_IP
          operator: CIDR_MATCH
          value: 10.0.0.0/8
      action:
        type: TARGET_INSTANCE
        instance-id: internal-gpu-1

    - id: route-model-rewrite
      name: Rewrite gpt-4 to claude-3
      enabled: true
      priority: 80
      conditions:
        - type: MODEL_NAME
          operator: EQUALS
          value: gpt-4
      action:
        type: TARGET_MODEL
        model-name: claude-3

Default is an empty list (model.rules: []), i.e. no rules enabled. YAML rules merge with Web-created rules: for the same id, the persisted (Web) rule overrides YAML.

API Reference¶

Base path: /api/config/rules

Create Rule Example¶

curl -X POST http://localhost:8080/api/config/rules \
  -H "Content-Type: application/json" \
  -H "Jairouter_Token: your-admin-token" \
  -d '{
    "name": "Route to vLLM by header",
    "priority": 100,
    "enabled": true,
    "conditions": [
      {"type": "HEADER", "field": "x-routing", "operator": "EQUALS", "value": "vllm"}
    ],
    "action": {"type": "TARGET_ADAPTER", "adapterName": "vllm"}
  }'

Batch Priority Example¶

curl -X PUT http://localhost:8080/api/config/rules/priority \
  -H "Content-Type: application/json" \
  -H "Jairouter_Token: your-admin-token" \
  -d '[{"id": "rule-id-1", "priority": 200}, {"id": "rule-id-2", "priority": 100}]'

Verification¶

1. Use AI Playground → Chat Test to send requests and observe routing
2. Check backend logs for Selected adapter / routing selection info
3. Or call /v1/* APIs with/without the conditional header and compare routing

Notes¶

1. Hot reload: rule changes take effect immediately, no restart needed
2. Persistence: Web-created rules are stored in StoreManager (key=rule_definitions) and restored on restart
3. Priority: rules with the same priority keep insertion order; semantics are "first match wins" — avoid overlapping rules
4. Performance: keep the rule count under ~100; per-request evaluation cost is negligible
5. TARGET_ADAPTER: if the specified adapter is not registered, it logs a warning and falls back to the instance-level adapter
6. HEADER conditions: only apply to /v1/* request paths (headers are used for matching only, not outbound forwarding)