AI Model Selection

AI Model Selection and Configuration

The eKuiper Manager integrates with OpenRouter to provide an AI-powered suite of tools including rule generation, stream analysis, and master-system troubleshooting. This section guides you through configuring AI models and managing provider quotas.

Overview

eKuiper Manager uses a curated selection of LLMs (Large Language Models) optimized for industrial logic, SQL generation, and system telemetry analysis. By default, the system is optimized for Google Gemini 1.5 Flash due to its high context window and speed, but it supports a wide variety of models through the OpenRouter API.

Configuration

To enable AI features, you must provide an OpenRouter API key in your environment configuration.

Environment Variable:

OPENROUTER_API_KEY=your_api_key_here

Supported Models

The interface provides a filtered list of models to ensure compatibility with eKuiper's specific industrial domain (e.g., generating valid SQL and JSON topologies).

Key supported models include:

• Gemini Series: google/gemini-2.0-flash-exp, google/gemini-flash-1.5 (Default)
• Llama Series: meta-llama/llama-3.3-70b-instruct, meta-llama/llama-3.1-405b-instruct
• Mistral/Qwen: mistralai/mistral-small-3.1-24b-instruct, qwen/qwen3-coder
• Specialized Models: openai/gpt-oss-120b, deepseek/deepseek-r1-0528

Fetching Available Models

You can retrieve the list of currently enabled models via the internal API:

Endpoint: GET /api/ai/models

Response Example:

[
  {
    "id": "google/gemini-2.0-flash-exp",
    "name": "Google: Gemini 2.0 Flash Experimental"
  },
  {
    "id": "meta-llama/llama-3.3-70b-instruct",
    "name": "Meta: Llama 3.3 70B Instruct"
  }
]

Usage in AI Modules

When interacting with the AI Assistant or Analysis tools, the modelName parameter can be passed to specify which LLM should process the request. If omitted, the system defaults to google/gemini-flash-1.5.

Example: Analyzing a Rule with a Specific Model

To perform a deep analysis of an eKuiper rule using a specific model:

Endpoint: POST /api/ai/analyze

Payload:

{
  "ruleId": "rule_thermal_monitor",
  "ekuiperUrl": "http://ekuiper-server:9081",
  "modelName": "meta-llama/llama-3.3-70b-instruct"
}

Quota and Rate Limit Management

Since the eKuiper Manager acts as a client to OpenRouter, usage is subject to your OpenRouter account balance and rate limits.

Error Handling

The API handles provider-specific errors gracefully. If your account hits a rate limit or runs out of credits, the system returns a standard error structure:

| HTTP Status | Message | Description | | :--- | :--- | :--- | | 429 | "AI Rate Limit Exceeded. Try again later." | Occurs when OpenRouter or the underlying provider (e.g., Google, Meta) throttles requests. | | 500 | "AI Provider Error: [Message]" | Occurs if there is an authentication failure or invalid model selection. |

Optimizing Usage

To minimize token consumption and stay within quotas:

1. Use Flash Models: Models like gemini-1.5-flash are significantly cheaper and faster for routine analysis.
2. Specific Prompts: Use the specific analyzer tools (e.g., stream-analyze or rule-analyze) rather than the master-chat for simple tasks, as they use targeted, smaller context windows.
3. Trace Duration: When using AI Log Capture (/api/ai/capture-logs), use the default duration level (10 seconds) to prevent large payload processing that can inflate token counts.

Advanced: Custom Model Aliases

If you are extending the manager and wish to add new models to the UI selection, update the ALLOWED_MODELS set within src/app/api/ai/models/route.ts. The interface automatically handles :free variants of these models if available on OpenRouter.