Introduction

ZAI is an enterprise intelligent service platform built on the Dathor Intelligent Engine. 【在此插入雷驼智能引擎的链接】

ZAI provides large-model aggregation capabilities and serves as the foundation for scenarios such as intelligent chat, knowledge bases, and agents. It includes a comprehensive monitoring system to view real-time usage statistics and analytical reports. It also provides multi-layer security protections, supporting call-limiting policies and content safety management.

Sanplex Agent depends on ZAI as a foundational service. This section describes how to install ZAI and use it at a basic level.

Note: ZAI 1.0 is a fully upgraded release and does not support upgrading from earlier beta versions. A fresh installation is required.

I. Install via Docker

ZAI can be deployed using Docker as follows.

Step 1: Install Docker

Ensure Docker is installed on your server.

Step 2: Create docker-compose.yml

Create a directory to store ZAI service files, for example ~/zai/. Then create an empty docker-compose.yml file under ~/zai/. You can do this via command line:

# Create a folder named zai (you can use another name) to store ZAI system files
mkdir zai && cd zai
# Create an empty docker-compose.yml file
touch docker-compose.yml 

Step 3: Configure docker-compose.yml

Open docker-compose.yml with any editor and add the following content:

services:
  # PostgreSQL database service; remove this service if you use your own database
  postgres:
    image: pgvector/pgvector:pg16
    container_name: postgres
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=postgres      # Postgres admin username
      - POSTGRES_PASSWORD=zai123456 # Postgres admin password
      - POSTGRES_DB=zai_base         # Initial database name
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - zai-network
  # Database initialization service; remove this service if you use your own database service
  db-init:
    image: postgres:16
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - POSTGRES_USER=postgres      # Same username as the postgres service
      - POSTGRES_PASSWORD=zai123456 # Same password as the postgres service
      - POSTGRES_DB=zai_base        # Target database name (pgvector extension will be enabled)
    # Connect to postgres via psql, create the pgvector extension; if the target DB does not exist, create it first; wait for port readiness before execution
    command: >
      bash -lc "set -euo pipefail;
        PGPASSWORD=$$POSTGRES_PASSWORD psql -h postgres -U $$POSTGRES_USER -d postgres -v ON_ERROR_STOP=1 -tAc \"SELECT 1 FROM pg_database WHERE datname='$$POSTGRES_DB'\" | grep -q 1 || \
        PGPASSWORD=$$POSTGRES_PASSWORD psql -h postgres -U $$POSTGRES_USER -d postgres -v ON_ERROR_STOP=1 -c \"CREATE DATABASE \\\"$$POSTGRES_DB\\\"\"; \
        PGPASSWORD=$$POSTGRES_PASSWORD psql -h postgres -U $$POSTGRES_USER -d $$POSTGRES_DB -v ON_ERROR_STOP=1 -c 'CREATE EXTENSION IF NOT EXISTS vector;'"
    networks:
      - zai-network
    restart: "no"
  # ZAI service
  app:
    image: qihangnet/zai:v1.0.26 # Use v1.0.26
    container_name: zai
    ports:
      - "8000:8000"
    environment:
      - LANG=zh_CN.UTF-8      # Container default language and encoding
      - LANGUAGE=zh_CN:zh     # Language priority
      - DB_HOST=postgres      # Database host (Compose service name)
      - DB_PORT=5432          # Database port
      - DB_USER=postgres      # Database username
      - DB_PASSWORD=zai123456 # Database password
      - DB_NAME=zai_base      # Database name
    depends_on:
      postgres:
        condition: service_healthy
      db-init:
        condition: service_completed_successfully
    networks:
      - zai-network
volumes:
  postgres_data:
networks:
  zai-network:
    driver: bridge 

Review the docker-compose.yml configuration (including comments) and adjust the following as needed.

Confirm the ZAI version

The currently recommended ZAI version is 1.0.26. If you want to use another version, replace v1.0.26 with the target version number.

 app:
    image: qihangnet/zai:v1.0.26 # Use v1.0.26
    container_name: zai 

Configure the ZAI service port

By default, ZAI uses port 8000. If you want to expose a different port on the host, adjust the host-side port in the mapping (host:container):

 app:
    ports:
      - "8000:8000" # Host 8000 → Container 8000 

Configure the database

ZAI requires a PostgreSQL database for storage. If you use your own database, remove the postgres and db-init services. Whether you use your own database or the Docker-provided PostgreSQL service, you must configure database connection information in the app service via the following environment variables:

 app:
    environment:
      - DB_HOST=postgres      # Database host; if using the postgres service in Compose, set to postgres
      - DB_PORT=5432          # Database port
      - DB_USER=postgres      # Database username
      - DB_PASSWORD=zai123456 # Database password
      - DB_NAME=zai_base      # Database name 

Environment variable reference:

If you are not using your own database (i.e., you use the PostgreSQL service in Compose), you must also configure connection settings in postgres and db-init. In the postgres service, set:

 postgres:
    environment:
      - POSTGRES_USER=postgres      # Database username
      - POSTGRES_PASSWORD=zai123456 # Database password
      - POSTGRES_DB=zai_base        # Database name 

Step 4: Install and start ZAI

For the first installation, Docker will pull images. The time required depends on your network. Run the following commands to start the service:

# Pull the latest images
docker-compose pull
# Run in the background
docker-compose up -d
# Check the app logs
docker-compose logs app 

Note: If you are using Docker Compose v2, replace docker-compose with docker compose.

Step 5: Access ZAI and initialize

After ZAI starts, open http://localhost:8000 in a browser.

图1

On first access, create an administrator account by following the prompts and setting an admin username and password.

图2

Afterwards, you can log in using the created credentials.

II. Upgrade ZAI

When a new ZAI version is released, go to the ZAI service directory and upgrade as follows.

Step 1: Stop the existing service

# Stop the existing service
docker-compose down 

If you want to remove old containers and data, add -v:

# Stop and delete old containers and data (Danger!)
docker-compose down -v 

Step 2: Update docker-compose.yml

Before upgrading, edit docker-compose.yml and replace the image version tag with the new version:

 app:
    image: qihangnet/zai:v1.0.26 # Use v1.0.26 

Step 3: Pull the latest images and start

# Pull the latest images
docker-compose pull
# Run in the background
docker-compose up -d
# Check the app logs
docker-compose logs app 

Additional References

• ZAI configuration and usage: 【在此插入8.4 ZAI服务控制面板使用的链接】
• Integrating ZAI with Sanplex Agent:【在此插入8.1 AI插件安装的链接】