huawei-cloud-ascend-command

Imported from huaweicloud/huaweicloud-skills (skills/ai/modelarts/huawei-cloud-ascend-command/SKILL.md). Install upstream with npx skills add huaweicloud/huaweicloud-skills --skill huawei-cloud-ascend-command. Copyright stays with the author.

Provides Huawei Ascend NPU natural language command translation and execution. Supports full npu-smi commands: device queries, configuration management, firmware upgrade, vNPU virtualization, certificate management, and compute power testing.

Overview

This skill provides natural language management for Huawei Ascend NPU devices via npu-smi commands. Supports both local direct execution and SSH remote modes.

Related Skills:

• huawei-cloud-ascend-remote-connect - General SSH remote operations (disk, Docker, logs, processes)
• npu-smi-skill - Alternative NPU management implementation
• model-deploy-test-skill - Model deployment and testing on Ascend DevServer

Capabilities:

• Device queries (health, temperature, power, HBM, ECC, topology)
• Configuration management (ECC, fan mode, fan speed)
• Firmware upgrade and status
• vNPU virtualization
• Certificate management
• Compute power testing (FLOPS)

Architecture

System Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                         Agent Orchestration                         │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  1. Parse user intent → Match Trigger keywords                        │    │
│  │  2. Prepare params → host, user, password explicit                 │    │
│  │  3. Invoke Skill → skill exec --name ascend-command            │    │
│  │  4. Return result → User                                          │    │
│  └────────────────────────────┬────────────────────────────────┘    │
│                               │ Explicit param passing (Rule 1)                │
│                               ▼                                     │
├─────────────────────────────────────────────────────────────────────┤
│                        User Interaction Layer                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  Natural Language Commands / CLI Arguments                  │    │
│  │  (NPU health check, temperature, firmware upgrade)          │    │
│  └────────────────────────────┬────────────────────────────────┘    │
│                               │                                     │
│                               ▼                                     │
├─────────────────────────────────────────────────────────────────────┤
│                      Skill Core Components (Stateless (Rule 2))           │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐      │
│  │ Command Executor│←→│   NPU Client    │←→│ Trend Recorder  │      │
│  │  - NL Parsing   │  │  - npu-smi cmd  │  │  - Metric Log   │      │
│  │  - Command Route│  │  - Local/SSH    │  │  - Trend Analysis│      │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘      │
│         │                      │                                     │
│         ▼                      ▼                                     │
├─────────────────────────────────────────────────────────────────────┤
│                    Huawei Cloud Ascend Infrastructure               │
│  Data Flow: Agent → Skill(host,user,pwd) → SSH → npu-smi → Response │
└─────────────────────────────────────────────────────────────────────┘

Agent Orchestration Flow

User request: "Query NPU status on 116.204.23.145"
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│ Agent parses intent                                               │
│   - Keyword "NPU" → Match ascend-command                       │
│   - IP address → SSH params needed                                  │
└─────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│ Agent prepares params (explicit, Rule 1)                              │
│   --host 116.204.23.145                                      │
│   --user root                                                │
│   --password ***                                             │
│   --command "NPU list"                                       │
└─────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│ Skill executes (Stateless, Rule 2)                                    │
│   - NpuClient(host, user, password) explicit receive                 │
│   - Execute npu-smi command                                        │
│   - Return result                                                 │
└─────────────────────────────────────────────────────────────┘
         │
         ▼
      Return to user

Related Skills (Agent orchestrated, no direct call, Rule 3)

Note: No direct calls between Skills, orchestrated by Agent based on user intent.

Prerequisites

System Requirements

• Python 3.8+
• Pure Python standard library implementation, no additional dependencies required

Environment Check

Prerequisite check: Python3 required

python3 --version  # Python3 >= 3.8

Authentication

Security rules (must be followed):

• Prohibited from reading, echoing, or printing password values
• Prohibited from asking the user to input passwords directly in the conversation
• Only allowed to read credentials from command line arguments

Parameter Confirmation

Input Parameters

Confirmation Requirements

The following operations require explicit user confirmation:

• ECC enable/disable
• Fan mode changes
• Firmware upgrade
• vNPU creation/deletion
• Certificate management

Core Workflow

Task 1: One-Shot Command Execution

python3 scripts/main.py --command "NPU health check"

Task 2: SSH Remote Execution

python3 scripts/main.py --command "NPU list" --host 192.168.1.100 --user root --password xxx

Task 3: Interactive Mode

python3 scripts/main.py

Usage Instructions

Device Queries

List all NPU devices
NPU health check
Get NPU temperature
Get NPU power usage
Get NPU memory info

Configuration Management

Set ECC mode
Set fan mode

Firmware Upgrade

Query firmware version
Upgrade firmware

Virtualization

Query vNPU info
Create vNPU

FLOPS Test

Run FLOPS test
Run FP32 FLOPS test
Run multi-device FLOPS test

Output Format

Standard Response Format

All command outputs follow a structured format:

{
  "status": "success",
  "command": "npu-smi info -l",
  "description": "List all NPU devices"
}

Error Response Format

[ERROR] <error-code>
Message: <error-description>
Suggestion: <troubleshooting-tip>

Verification Method

Basic Verification Steps

1. Environment Check

   python3 --version  # Verify Python 3.8+

2. Local Command Test

   python3 scripts/main.py --command "NPU list"

3. Remote Command Test

   python3 scripts/main.py --host <ascend-ip> --user root --password <pwd> --command "NPU health check"

Expected Results

Script Files

Entry File

• main.py: Skill entry file (required)
  • Function: Provide interactive mode, one-shot mode, SSH remote mode
  • Supports: Command line arguments, interactive prompt

Core Scripts

• executor.py: NPU command executor (main entry)

  • Function: Natural language parsing, command routing, sensitive operation confirmation
  • Supported commands: Device queries, configuration, firmware upgrade, virtualization, certificate management
  • Core methods: handle_command(text), confirm_sensitive()

• npu_client.py: NPU client

  • Function: Wraps npu-smi command execution, supports local and SSH remote execution
  • Core methods: list_devices(), get_health(), get_temperature(), get_power(), get_memory(), set_ecc_enable(), upgrade_query(), create_vnpu(), get_tls_cert()
  • Optimization: SSH ControlMaster, batch execution, parallel FLOPS testing

Command Translation Mapping

Device Queries

Health Check

Temperature/Power/Memory

Configuration

Firmware Upgrade

Virtualization

Certificate Management

FLOPS Test (ascend-dmi)

Default behavior: single device FP16, fast return (~2 seconds)

Execution strategy:

• Single device: Direct execution, ~2 seconds return
• Multi-device: Async parallel execution, total ~2 seconds (not serial 16 seconds)
• Precision: Default fp16, supports fp32/bf16/int8/hf32

Performance Optimization

Troubleshooting

Command Not Recognized

• Check if input contains supported keywords
• Try using more explicit commands

SSH Connection Failed

• Verify SSH parameters are correct
• Ensure SSH service is running on target machine

npu-smi Not Available

• Ensure CANN and npu-smi are installed on target machine
• Check LD_LIBRARY_PATH environment variable

Notes

Security Warnings

• Sensitive operations require user confirmation before execution
• Passwords are only stored in memory during session
• Blocked commands cannot be bypassed

Limitations

• Requires npu-smi or ascend-dmi installed on target machine
• SSH password authentication only (no interactive password prompt)

Best Practices

Best Practices

1. Connection Mode Selection

   • Local direct: For NPU installed on local machine
   • SSH remote: For managing remote Ascend servers

2. Command Execution Tips

   • Sensitive ops (firmware upgrade, config change) require user confirmation
   • Test on single card before batch operations

3. Performance Monitoring

   • Regularly check NPU temperature and power
   • Monitor HBM usage to avoid OOM

4. Troubleshooting

   • First check NPU health: npu-smi info
   • View detailed error log: npu-smi info -t board -i <npu_id>
   • See troubleshooting.md

5. Trigger Keywords

   • Chinese: NPU, 昇腾, 显存, 算力, 温度, 功耗, 固件, 虚拟化
   • English: npu, ascend, temperature, power, HBM, firmware, vNPU, FLOPS

Directory Structure

huawei-cloud-ascend-command/
├── SKILL.md                    # Skill description (required)
├── scripts/                    # Scripts directory (required)
│   ├── __init__.py             # Module export
│   ├── main.py                 # Skill entry file (required)
│   ├── executor.py             # NPU command executor
│   └── npu_client.py           # NPU client
└── references/                 # Reference documentation
    ├── acceptance-criteria.md  # Acceptance criteria
    ├── verification-method.md  # Verification steps
    ├── troubleshooting.md      # Troubleshooting guide
    ├── device-queries.md       # Device queries reference
    ├── configuration.md        # Configuration reference
    ├── firmware-upgrade.md     # Firmware upgrade reference
    ├── virtualization.md       # Virtualization reference
    └── certificate-management.md # Certificate management

References

Technical Support

• Ascend Official Documentation: https://www.hiascend.com/document
• npu-smi Command Reference: https://www.hiascend.com/document/detail/zh/Atlas%20200I%20A2/260RC1/re/npu/npusmi_007.html