Overview

ZAI is an enterprise-grade intelligent service platform built on the Dathor Intelligent Engine. It provides model aggregation capabilities and foundational support for scenarios such as Intelligent Conversation, Knowledge Base, and Agents. ZAI also includes a comprehensive monitoring system for real-time usage statistics and analytics reports, plus multi-layer security controls such as invocation rate limiting and content safety management.

Sanplex Agent capabilities rely on ZAI as the underlying service. This section explains how to install ZAI and perform basic setup.

Note: ZAI 1.0 is a major upgrade and does not support in-place upgrades from earlier beta releases. You must perform a fresh installation.

Install via Docker

ZAI currently supports deployment via Docker. Follow these steps:

Step 1: Install Docker

Ensure Docker is installed on your host machine.

Step 2: Create docker-compose.yml

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

# Create a folder named zai (or another name) to store system files generated by the ZAI service
mkdir zai && cd zai
# Create a blank 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. If you use a self-managed database, remove this service.
  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. If you use your own database, remove this service.
  db-init:
    image: postgres:16
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - POSTGRES_USER=postgres       # Must match the postgres service username
      - POSTGRES_PASSWORD=zai123456  # Must match the postgres service password
      - POSTGRES_DB=zai_base         # Target database name (pgvector extension will be enabled)
    # Connect via psql to create pgvector extension. If the database does not exist, create it first.
    # Wait for the port to be ready before executing.
    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.38 # Use version v1.0.38
    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 

After adding the content, review the configuration (including the comments) and adjust the following items as needed:

1) Confirm the ZAI Service Version

The currently recommended ZAI version is 1.0.38. If you need a different version, replace v1.0.38 with your target version:

app:
  image: qihangnet/zai:v1.0.38 # Use version v1.0.38
  container_name: zai 

2) Configure the ZAI Service Port

ZAI uses port 8000 by default. If you want to expose a different host port, modify the left-hand side of the mapping (host:container):

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

3) Configure the Database

ZAI requires a PostgreSQL database to store data.

• If you use a self-managed database, remove the postgres and db-init services.
• Whether you use a self-managed database or the Compose-provided PostgreSQL service, you must configure the database connection in the app service via the following environment variables:

app:
  environment:
    - DB_HOST=postgres       # Database host. If using the Compose postgres service, 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 do not use a self-managed database (i.e., you use the Compose PostgreSQL service), configure connection settings in both postgres and db-init. In postgres, set:

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

Step 4: Install and Start the ZAI Service

The first installation requires pulling images, and the time required depends on network conditions (it may take several minutes). Run:

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

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

Step 5: Access ZAI and Initialize

After ZAI starts, open the following in your browser:

http://localhost:8000 

图1

On first access, create an administrator account. Follow the prompts to set the admin username and password.

图2

After that, log in using the created credentials.

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 existing services
docker-compose down 

If you want to delete old containers and data volumes, add the -v flag:

# Stop and remove old containers (WARNING: deletes data volumes)
docker-compose down -v 

Step 2: Update docker-compose.yml

Before upgrading, update the ZAI image version in docker-compose.yml by replacing the image tag with the new version:

app:
  image: qihangnet/zai:v1.0.38 # Use version v1.0.38 

Step 3: Pull the Latest Image and Restart

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

Additional References

Dathor Intelligent Engine: https://dathor.cn/products/engine
Collabora installation options (if needed): https://www.collaboraoffice.com/code-install-and-test/
ZAI image versions: https://hub.docker.com/r/qihangnet/zai
ZAI control panel guide: https://www.zentao.net/book/zentaopms/zai-install-copy-copy-1821.html?releaseID=21 （届时，将占位符链接替换为 Sanplex 官方文档 URL）
ZAI deployment guide (reference): https://www.zentao.net/book/zentaopms/1819.html （届时，将占位符链接替换为 Sanplex 官方文档 URL）