M Huawei LiteLLM UI

Setup tutorial for Huawei LiteLLM UI

Follow these steps to run the complete Docker Compose stack, connect an existing LiteLLM deployment, verify that models and pricing work, and open the simplified Huawei LiteLLM UI.

Start from scratch Use existing LiteLLM GitHub repository

Before You Start

Choose one path. The fresh install is the supported default. The existing-LiteLLM path is for teams that already operate LiteLLM and want to add Huawei MaaS models and the simpler UI.

Tutorial

Prerequisites

  • Docker and Docker Compose
  • A Huawei Cloud MaaS API key
  • curl for downloading the Compose files
  • A stable LITELLM_SALT_KEY before adding keys or models

What the full stack starts

  • LiteLLM API on localhost:4000
  • Simplified Huawei LiteLLM UI on localhost:3002
  • Postgres for LiteLLM state
  • Catalog sync and Huawei model seed jobs
1. Fresh install 2. Verify the stack 3. Use the UI 4. Existing LiteLLM

1. Fresh Install

This path starts everything the project needs. Use it unless you already have a production LiteLLM instance.

Recommended

Download the runtime files

curl -fsSL https://raw.githubusercontent.com/j0taaa/litellm-huawei/main/scripts/install-release.sh | sh
cd huawei-litellm-ui

This downloads docker-compose.yml and creates .env from CLI questions. It does not clone the source repository.

Answer the setup questions

Huawei MaaS API key:
LiteLLM master key [generated, press Enter to use it]:
LiteLLM salt key [generated, press Enter to use it]:
Postgres password [generated, press Enter to use it]:
LiteLLM API host port [4000]:
Huawei LiteLLM UI host port [3002]:

The installer writes the answers to .env. For automated installs, set the same values as environment variables before running the script.

Start the stack

docker compose up -d

Docker pulls the published images from GHCR: litellm-huawei-litellm, litellm-huawei-tools, and litellm-huawei-ui.

2. Verify the Stack

Run these checks after docker compose up -d.

Check containers 
docker compose ps
Check LiteLLM health 
curl http://localhost:4000/health/readiness
List available models 
curl -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  http://localhost:4000/v1/models
Send a test request 
curl http://localhost:4000/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.1",
    "messages": [{"role": "user", "content": "Reply with OK only."}],
    "max_tokens": 8
  }'

3. Use the Huawei LiteLLM UI

Open http://localhost:3002 after the stack is running.

Keys

Create, edit, clone, disable, and delete API keys. Configure model access, budgets, token quotas, rate limits, access schedules, and prompt policies.

Teams

Create teams with the same controls as keys. Team settings are applied to keys assigned to that team.

Stats and testing

Use the stats pages to inspect spend by model, key, and team. Use the test page to send chat requests through a selected key.

The UI signs in through LiteLLM. Use the LiteLLM account credentials configured for your deployment.

4. Existing LiteLLM

Follow this path if you already have LiteLLM and Postgres running, and you want to add Huawei MaaS models and the Huawei LiteLLM UI.

Advanced
For correct Huawei tiered spend tracking, your LiteLLM instance must load the project callback. If you only run the UI against an existing LiteLLM without that callback, key/team management still works, but Huawei-specific pricing, token quotas, prompt policies, and schedule enforcement will not be complete.

Download the release Compose file

mkdir huawei-litellm-ui
cd huawei-litellm-ui
mkdir generated

Use the published tools image for sync and seed jobs

docker run --rm \
  -e CATALOG_URL=https://catalog.hwctools.site/models \
  -v "$PWD/generated:/workspace/generated" \
  ghcr.io/j0taaa/litellm-huawei-tools:latest \
  python -m huawei_litellm.sync

docker run --rm \
  -e LITELLM_BASE_URL=https://your-litellm.example.com \
  -e LITELLM_MASTER_KEY=your-master-key \
  -e MODEL_SEED_PATH=/workspace/generated/model_seed.json \
  -v "$PWD/generated:/workspace/generated:ro" \
  ghcr.io/j0taaa/litellm-huawei-tools:latest \
  python -m huawei_litellm.seed_models

The tools image contains the catalog sync, model seed code, Huawei callback, and pricing package. You do not need a source checkout to generate the runtime files.

Connect the Huawei callback to your existing LiteLLM

litellm_settings:
  callbacks: custom_callbacks.proxy_handler_instance
  drop_params: true
  turn_off_message_logging: true

Your LiteLLM container must mount the generated volume or copy the generated custom_callbacks.py, huawei_litellm/, and huawei_catalog.json.

Run the simple Huawei LiteLLM UI against your LiteLLM

docker run -d --name huawei-litellm-ui \
  -p 3002:3001 \
  -e NODE_ENV=production \
  -e UI_PORT=3001 \
  -e LITELLM_BASE_URL=https://your-litellm.example.com \
  -e LITELLM_MASTER_KEY=your-master-key \
  -e UI_DATABASE_URL=postgresql://user:password@host:5432/litellm \
  -e UI_SESSION_SECRET=change-this-secret \
  ghcr.io/j0taaa/litellm-huawei-ui:latest

The UI uses LiteLLM login and writes prompt-policy metadata through the same LiteLLM/Postgres environment.

Troubleshooting

Common checks when the setup does not behave as expected.

Models are missing

Check the config-sync and model-seed logs. The seed job reads generated/model_seed.json.

Upstream calls fail

Confirm HUAWEI_MAAS_API_KEY is set in the LiteLLM container and that the key is valid for Huawei MaaS.

Stored credentials fail after restart

LITELLM_SALT_KEY encrypts stored credentials. Changing it can break existing keys and model credentials.

Production Notes

Set strong secrets, keep the salt key stable, back up Postgres, and test tiered pricing after LiteLLM upgrades with prompts that cross 32K tokens.