Adapter Configuration Guide¶

Overview¶

JAiRouter supports adding new adapters through configuration-driven approach, without writing code. This applies to all OpenAI-compatible APIs (such as DeepSeek, Zhipu, Moonshot, etc.).

Supported Providers¶

Method 1: Web UI Configuration (Recommended)¶

Step 1: Navigate to Adapter Management¶

1. Login to JAiRouter Admin Panel
2. Click Configuration → Adapter Management in the left sidebar

Step 2: Create New Adapter¶

Click the 「Create Adapter」 button in the top-right corner, fill in the form:

Click 「Save」 to complete.

Step 3: Use in Instance Configuration¶

Navigate to Configuration → Instance Management, add or edit an instance:

• Select the created adapter (e.g., deepseek) in the Adapter dropdown
• Fill in Base URL (e.g., https://api.deepseek.com)
• Add authentication in Custom Headers: Authorization: Bearer sk-your-api-key

Workflow¶

┌─────────────────────┐     ┌─────────────────────┐
│  1. Adapter Mgmt    │ ──→ │  2. Create adapter  │
│     Page            │     │     e.g. deepseek   │
└─────────────────────┘     └──────────┬──────────┘
                                       │
                                       ▼
┌─────────────────────┐     ┌─────────────────────┐
│  3. Instance Mgmt   │ ──→ │  4. Select adapter  │
│     Page            │     │    Set URL & key    │
└─────────────────────┘     └─────────────────────┘

Method 2: YAML Configuration¶

Step 1: Edit adapter.yml¶

Edit file src/main/resources/config/router/adapter.yml:

model:
  adapter: gpustack  # Global default adapter

adapter-definitions:
  deepseek:
    type: openai-compatible
    capabilities:
      chat: true
      embedding: true
      streaming: true
    auth:
      header-name: Authorization
      header-prefix: "Bearer "

Step 2: Use in services.yml¶

Edit file src/main/resources/config/router/services.yml:

model:
  services:
    chat:
      adapter: deepseek  # Use the deepseek adapter defined above
      instances:
        - name: deepseek-chat
          baseUrl: https://api.deepseek.com
          path: /v1/chat/completions
          headers:
            Authorization: "Bearer sk-your-api-key-here"
          weight: 1
          status: active

Step 3: Restart Application¶

mvn spring-boot:run -Pfast

Common Adapter Configuration Examples¶

DeepSeek¶

adapter-definitions:
  deepseek:
    type: openai-compatible
    capabilities:
      chat: true
      embedding: true
      streaming: true
    auth:
      header-name: Authorization
      header-prefix: "Bearer "

Zhipu GLM¶

adapter-definitions:
  zhipu:
    type: openai-compatible
    capabilities:
      chat: true
      embedding: true
      streaming: true
    auth:
      header-name: Authorization
      header-prefix: "Bearer "

Moonshot¶

adapter-definitions:
  moonshot:
    type: openai-compatible
    capabilities:
      chat: true
      streaming: true
    auth:
      header-name: Authorization
      header-prefix: "Bearer "

Custom Auth Header API¶

adapter-definitions:
  custom-api:
    type: openai-compatible
    capabilities:
      chat: true
      streaming: true
    auth:
      header-name: X-API-Key    # Custom auth header name
      header-prefix: ""          # No prefix

Verify Configuration¶

Via Web UI¶

1. Navigate to AI Playground → Chat
2. Select the service and model using the new adapter
3. Send a test message

Via API¶

curl -X POST http://localhost:9900/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

API Reference¶

Create Adapter API Example¶

curl -X POST http://localhost:9900/api/config/adapter \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deepseek",
    "type": "openai-compatible",
    "capabilities": {
      "chat": true,
      "embedding": true,
      "streaming": true
    },
    "auth": {
      "headerName": "Authorization",
      "headerPrefix": "Bearer "
    }
  }'

Notes¶

1. Adapter name: Only letters, numbers, underscores and hyphens allowed
2. Built-in adapters cannot be deleted: normal, claude, gemini, ollama, etc.
3. Configurable adapters can be modified anytime: Changes take effect immediately
4. Authentication: Most cloud APIs use Authorization: Bearer {key}, no need to change defaults