# z-image

**Repository Path**: alan-ding/z-image

## Basic Information

- **Project Name**: z-image
- **Description**: z-image 是一款功能强大且高效的图像生成模型，拥有60 亿个参数。这里介绍如何本地部署，及作为mcp使用。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## mirrors
- Tsinghua University : https://pypi.tuna.tsinghua.edu.cn/simple
- Alibaba Cloud : https://mirrors.aliyun.com/pypi/simple/
- Tencent Cloud : https://mirrors.cloud.tencent.com/pypi/simple/
- University of Science and Technology of China : https://pypi.mirrors.ustc.edu.cn/simple/

## hugging face mirror
set HF_ENDPOINT=https://hf-mirror.com

## install huggingface-cli
pip install huggingface-hub

## download modal
hf download  Tongyi-MAI/Z-Image-Turbo --local-dir ./modal

## check cuda version
nvidia-smi
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 572.83                 Driver Version: 572.83         CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                  Driver-Model | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 5090 D    WDDM  |   00000000:02:00.0 Off |                  N/A |
|  0%   24C    P8             18W /  575W |       0MiB /  32607MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+
                                                                                         
+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+
CUDA分为两种，驱动API和运行API，驱动API指的是显卡驱动支持的最高cuda版本，我们运行程序时用的是运行API。
nvidia-smi显示的是驱动所能支持的最大运行API版本，nvcc --version查看的是CUDA的运行API版本。
```
import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
```
![alt text](./test/image.png)

## install cuda tookit
https://developer.nvidia.com/cuda-12-1-0-download-archive


## install torch
```
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
```

## finally running check
BASIC PYTORCH CUDA STATUS:
nvcc --version
--------------------------------------------------
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2025 NVIDIA Corporation
Built on Wed_Jan_15_19:38:46_Pacific_Standard_Time_2025
Cuda compilation tools, release 12.8, V12.8.6

## ...
- to enable running torch cuda version, using `pip` instead of `uv`
- add module namespace with prefix `src` in code
- update modal path, parameter in `inference.py`

## how to run
1. remove packages below from `global-requirements.txt`
```
torch==2.9.1+cu128
torchaudio==2.9.1+cu128
torchvision==0.24.1+cu128
```

2. install global modules
`pip install -r global-requirements.txt`

3. install torch
```
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
```

4. use global cuda
set `include-system-site-packages = true` in `.venv\pyvenv.cfg`


5. install project dependency
```
uv sync
uv lock
```

6. start as mcp
```
python main.py
```


## test
1024X1024
![alt text](./image.png)

mcp server
![alt text](image-1.png)

## enhancement result from Trae agent
![alt text](白毛衣女孩窗边阅读.webp)
![alt text](test/女孩窗边读书.webp)
![alt text](test/亚洲女孩微笑肖像.jpg)
![alt text](窗边看书的漂亮女孩.jpg)
![alt text](test/亚洲男人爬长城.webp)