Since V4.0.0, obdiag supports starting the AI intelligent diagnostic assistant through the obdiag tool ai_assistant command. The assistant supports natural language interaction, can understand user intentions and invoke obdiag's collection, analysis, inspection, root cause analysis and other capabilities to perform diagnosis.
Attention
This feature is BETA version and requires configuration of LLM API (such as OpenAI or compatible interface). Optionally configure MCP for enhanced capabilities.
Function introduction
Capabilities |
Description |
|---|---|
| Natural language interaction | Use natural language to describe diagnostic requirements (such as "collect logs in the last hour", "check cluster health", "do a root cause analysis"), and the assistant will parse the intent and call the corresponding obdiag command. |
| Built-in MCP tool | Obdiag's built-in MCP service is used by default, and capabilities such as gather/analyze/check/rca are exposed to LLM in the form of tools, and LLM decides when to call and what parameters to pass. |
| Optional external MCP | External MCP services can be configured in ai.yml to extend more tools or data sources. |
Preconfiguration
AI related items need to be configured before use, and the configuration file path is ~/.obdiag/ai.yml. Can be copied from conf/ai.yml.example and modified:
# For source install, copy from obdiag source tree: conf/ai.yml.example
cp /opt/oceanbase-diagnostic-tool/conf/ai.yml.example ~/.obdiag/ai.yml
Configuration file structure description
ai.yml is divided into three parts: llm (large model), mcp (MCP protocol), ui (interface and prompts).
LLM configuration (required)
Used to communicate with OpenAI or services compatible with OpenAI interfaces, api_key is required (environment variable OPENAI_API_KEY can also be used).
llm:
api_type: openai # Type: openai or compatible API
api_key: "" # API key; or set OPENAI_API_KEY
base_url: "" # API base URL; or OPENAI_BASE_URL
model: gpt-4 # Model name, e.g. gpt-4, gpt-3.5-turbo, qwen-plus
temperature: 0.7 # Randomness 0–2; lower is more stable
max_tokens: 2000 # Max tokens per reply
system_prompt: "" # Optional custom system prompt; empty uses built-in
```**base_url example**:
- OpenAI official: <https://api.openai.com/v1>
- Azure OpenAI: <https://your-resource.openai.azure.com/openai/deployments/your-deployment>
- Custom: <https://your-api-server.com/v1>
#### MCP configuration (optional)
The built-in MCP service is enabled by default, and tools such as obdiag's gather/analyze/check/rca can be used without additional configuration. Configuring `mcp.servers` is only required when using **external MCP services**.
```yaml
mcp:
enabled: true # Enable MCP tools
servers: "" # External MCP JSON; empty uses built-in only
# For external MCP, JSON string compatible with mcp.json, e.g.:
# servers: |
# {
# "my_server": {
# "command": "some-mcp-command",
# "args": ["stdio"]
# },
# "http_server": {
# "url": "http://127.0.0.1:8000/mcp"
# }
# }
```**Examples of built-in MCP tools**: gather_log, gather_sysstat, gather_perf, gather_obproxy_log, gather_ash, gather_awr, analyze_log, check, check_list, rca_run, rca_list, tool_io_performance, etc. Enter `tools` in interactive mode to view the list of currently loaded tools.
#### UI configuration (optional)
```yaml
ui:
show_welcome: true # Show welcome banner on startup
show_beta_warning: true # Show BETA warning
clear_screen: true # Clear screen before interactive session
prompt: "obdiag AI> " # Interactive prompt prefix
Notes
- BETA function: The interface and behavior may be adjusted with the version. If you encounter any problems, please go to GitHub Issues for feedback.
- API Fee: Calling external LLM will incur fees, please control the usage by yourself.
- Sensitive information: obdiag will not send sensitive information such as cluster passwords to LLM; only the parameters required to execute the obdiag subcommand will be passed in as needed.
- Network and Permissions: When executing gather/check/rca isochronous, it depends on the cluster configuration specified by
-cand the SSH/network reachability of the current machine to the cluster, which is consistent with the requirements of directly executing the obdiag subcommand.
Command description
obdiag tool ai_assistant [options]
```| Option name | Is it required | Data type | Default value | Description |
|--------|----------|----------|--------|------|
| -c | No | string | `~/.obdiag/config.yml` | obdiag cluster configuration file path; the AI assistant will use this configuration to connect to the cluster when calling gather/check/rca, etc. |
| --config_password | No | string | Default is empty | obdiag When using an encrypted configuration file, you need to pass in the corresponding password through this option. For details, see [Configuration File Encryption](801.crypto_config.md). |
| -h/--help | No | - | - | No need to pass a value. Configuration in the command means to view the command help. |
| -v/--verbose | No | - | - | There is no need to pass a value. The configuration in the command means that detailed logs will be output. |
### Commands in interactive mode
After startup, it enters interactive mode. In addition to natural language questions, it also supports the following commands:
| Command | Description |
|------|------|
| `help`/`?` | Display help and example questions. |
| `exit`/`quit`/`q` | Exit the AI assistant. |
| `clear` | Clear the conversation history of the current session (does not affect the executed obdiag command). |
| `history` | View the conversation history of the current session. |
| `tools` | Lists currently available diagnostic tools (built-in MCP and connected external MCP tools). |
## Usage example
### Start AI Assistant
```shell
obdiag tool ai_assistant
If using custom cluster configuration or encryption configuration, examples are as follows:
obdiag tool ai_assistant -c /path/to/config.yml
obdiag tool ai_assistant -c ~/.obdiag/config.yml.encrypted --config_password=your_secret
Interaction example
$ obdiag tool ai_assistant
╔══════════════════════════════════════════════════════════════════════════╗
║ obdiag AI Assistant ║
╠══════════════════════════════════════════════════════════════════════════╣
║ Welcome! I'm your AI assistant for OceanBase diagnostics. ║
║ You can ask me to: Collect logs, Analyze data, Run health checks, ║
║ Perform root cause analysis, and more. ║
║ Type 'exit' or 'quit' to end. Type 'help' for more. ║
╚══════════════════════════════════════════════════════════════════════════╝
obdiag AI> Collect logs from the last hour
AI: Running log collection...
Command: obdiag gather log --since 1h
...
obdiag AI> Check cluster health
AI: Running cluster inspection...
Command: obdiag check run
...
obdiag AI> tools
🔌 Using built-in MCP server
📦 Loaded 12 tools: gather_log, gather_sysstat, gather_perf, ...
obdiag AI> exit
Goodbye!
FAQ
Error: OpenAI API key is required Please configure Key in
llm.api_keyin~/.obdiag/ai.yml, or set the environment variableOPENAI_API_KEY.**How to use only built-in capabilities without connecting to the external network? ** Configure
llmto serve an accessible OpenAI-compatible intranet or local model (base_url+api_key), and keepmcp.serversempty to use the built-in MCP tool.**How to check which tools were used in this session? ** Enter
toolsin the interaction to view the list of loaded tools and MCP connection status; if-vis turned on during execution, a more detailed call log will be output.