当前位置：首页 > news >正文

LiuJuan20260223Zimage部署教程：Docker Compose一键编排Xinference+Gradio+Redis缓存

news 2026/9/1 9:05:10

LiuJuan20260223Zimage部署教程：Docker Compose一键编排Xinference+Gradio+Redis缓存

想快速搭建一个属于自己的AI绘画服务，专门生成LiuJuan风格的图片吗？今天，我们就来手把手教你如何通过Docker Compose，一键部署一个集成了Xinference模型服务、Gradio可视化界面和Redis缓存的完整系统。整个过程就像搭积木一样简单，无需复杂的配置，几分钟就能让你的专属AI画师上线。

这个教程的目标很明确：让你从零开始，成功部署并运行LiuJuan20260223Zimage模型。你不需要是Docker专家，也不需要懂复杂的AI模型部署，跟着步骤走就行。我们将使用Docker Compose这个工具，它能帮你把模型服务、Web界面和缓存系统这三个“零件”自动组装好，省时省力。

1. 环境准备与快速部署

在开始之前，请确保你的服务器或本地电脑已经安装了Docker和Docker Compose。这是我们的“施工工具”。如果你还没有安装，可以先去Docker官网下载对应你操作系统的安装包，安装过程通常很简单。

1.1 获取部署文件

首先，我们需要一个“施工图纸”，也就是Docker Compose的配置文件。这个文件定义了我们要启动哪些服务以及它们之间的关系。

创建一个新的文件夹，比如叫做liujuan-ai，然后在这个文件夹里创建一个名为docker-compose.yml的文件。用你喜欢的文本编辑器（如VS Code、Notepad++）打开它，将以下内容复制进去：

version: '3.8' services: # 1. Xinference 模型推理服务 xinference: image: registry.cn-hangzhou.aliyuncs.com/csdn_mirrors/liujuan20260223zimage:latest container_name: liujuan_xinference restart: unless-stopped ports: - "9997:9997" # Xinference服务端口 volumes: - ./xinference_data:/root/.xinference # 挂载数据卷，持久化模型数据 command: > bash -c " xinference-local -H 0.0.0.0 --port 9997 & tail -f /dev/null " healthcheck: test: ["CMD", "curl", "-f", "http://localhost:9997/v1/models"] interval: 30s timeout: 10s retries: 3 start_period: 40s networks: - liujuan_network # 2. Gradio WebUI 界面服务 gradio_ui: image: gradio/gr container_name: liujuan_gradio_ui restart: unless-stopped depends_on: xinference: condition: service_healthy # 等待xinference健康后再启动 ports: - "7860:7860" # Gradio默认端口，可在浏览器访问 volumes: - ./app:/app # 挂载我们的应用代码 working_dir: /app command: python app.py networks: - liujuan_network # 3. Redis 缓存服务（用于提升体验，可选但推荐） redis: image: redis:7-alpine container_name: liujuan_redis restart: unless-stopped ports: - "6379:6379" volumes: - ./redis_data:/data # 持久化Redis数据 command: redis-server --appendonly yes # 开启持久化 networks: - liujuan_network networks: liujuan_network: driver: bridge

这个文件做了三件事：

启动Xinference服务：拉取并运行包含LiuJuan20260223Zimage模型的镜像，在9997端口提供服务。
启动Gradio Web界面：提供一个美观的网页界面，让你可以通过浏览器输入文字、生成图片。
启动Redis缓存：缓存一些中间结果，让重复生成或类似提示词的图片生成更快。

1.2 创建Gradio应用文件

接下来，我们需要创建Gradio界面的代码。在同一个liujuan-ai文件夹下，创建一个app子文件夹，然后在里面创建一个app.py文件。

# app/app.py import gradio as gr import requests import json import time from PIL import Image import io import redis import os # 连接到Redis缓存（如果启用） REDIS_HOST = os.getenv("REDIS_HOST", "redis") # Docker Compose中服务名即主机名 REDIS_PORT = int(os.getenv("REDIS_PORT", 6379)) try: r = redis.Redis(host=REDIS_HOST, port=REDIS_PORT, decode_responses=True, socket_connect_timeout=3) r.ping() USE_REDIS = True print("Redis缓存已连接。") except redis.ConnectionError: USE_REDIS = False print("未连接Redis缓存，将直接调用模型。") # Xinference 服务地址 XINFERENCE_HOST = os.getenv("XINFERENCE_HOST", "xinference") # Docker Compose中服务名 XINFERENCE_PORT = os.getenv("XINFERENCE_PORT", "9997") MODEL_UID = "liujuan-model" # 假设模型启动后的UID，可根据实际情况调整 BASE_URL = f"http://{XINFERENCE_HOST}:{XINFERENCE_PORT}/v1" def generate_image(prompt, negative_prompt="", steps=20, width=512, height=512): """ 调用Xinference服务生成图片。 """ # 构建缓存键 cache_key = f"img:{prompt}:{negative_prompt}:{steps}:{width}:{height}" if USE_REDIS: cached_result = r.get(cache_key) if cached_result: print(f"缓存命中: {cache_key}") # 这里缓存的是图片的base64或路径，示例中我们缓存空，实际可扩展 # 为简化，本例缓存未存储图片数据，仅作流程演示 pass # 准备请求数据 data = { "model": MODEL_UID, "prompt": prompt, "negative_prompt": negative_prompt, "num_inference_steps": steps, "width": width, "height": height, "num_images": 1 } try: # 调用Xinference的图像生成接口 # 注意：实际端点可能为 /v1/images/generations 或 /v1/completions，请根据Xinference文档调整 response = requests.post(f"{BASE_URL}/images/generations", json=data, timeout=60) if response.status_code == 200: result = response.json() # 假设返回结构包含图像的base64数据 # 实际解析需要根据Xinference API的响应格式调整 image_b64 = result['data'][0]['b64_json'] # 示例字段名 import base64 image_data = base64.b64decode(image_b64) image = Image.open(io.BytesIO(image_data)) # 存储到缓存（示例存储生成时间戳） if USE_REDIS: r.setex(cache_key, 300, time.time()) # 缓存5分钟 return image else: return f"生成失败: {response.status_code} - {response.text}" except requests.exceptions.RequestException as e: return f"请求模型服务出错: {e}" except Exception as e: return f"处理图像时出错: {e}" # 创建Gradio界面 with gr.Blocks(title="LiuJuan AI 图像生成器", theme=gr.themes.Soft()) as demo: gr.Markdown("# 🎨 LiuJuan 风格图像生成器") gr.Markdown("输入描述，生成独具特色的LiuJuan风格图片。") with gr.Row(): with gr.Column(scale=1): prompt_input = gr.Textbox( label="正面提示词", placeholder="例如: LiuJuan, 精致的面庞，优雅的古风装扮，站在桃花树下", lines=3 ) negative_input = gr.Textbox( label="负面提示词 (不希望出现的元素)", placeholder="例如: 丑陋，模糊，低质量，多余的手指", lines=2 ) with gr.Row(): steps_slider = gr.Slider(minimum=10, maximum=50, value=20, step=1, label="生成步数") width_slider = gr.Slider(minimum=256, maximum=1024, value=512, step=64, label="图片宽度") height_slider = gr.Slider(minimum=256, maximum=1024, value=512, step=64, label="图片高度") generate_btn = gr.Button("生成图像", variant="primary", size="lg") with gr.Column(scale=1): output_image = gr.Image(label="生成的图像", type="pil") status_text = gr.Textbox(label="状态", interactive=False) # 示例提示词 examples = gr.Examples( examples=[ ["LiuJuan, 古风美女，手持团扇，背景是江南水乡，工笔画风格"], ["LiuJuan, 未来科技感，赛博朋克风格，霓虹灯光，机械细节"], ["LiuJuan, 童话风格，坐在巨大的蘑菇上，周围飞舞着发光精灵"] ], inputs=prompt_input, label="试试这些示例提示词" ) # 绑定按钮点击事件 def on_generate(prompt, negative_prompt, steps, width, height): if not prompt.strip(): return None, "提示词不能为空！" status = "正在生成，请稍候..." yield None, status result = generate_image(prompt, negative_prompt, steps, width, height) if isinstance(result, Image.Image): status = "生成成功！" return result, status else: status = result return None, status generate_btn.click( fn=on_generate, inputs=[prompt_input, negative_input, steps_slider, width_slider, height_slider], outputs=[output_image, status_text] ) gr.Markdown("### 使用小贴士") gr.Markdown(""" - **核心提示词**：在描述中包含 `LiuJuan` 以获得最佳风格效果。 - **细节描述**：描述越具体，生成结果越符合预期（如服装、场景、动作、光影）。 - **负面提示词**：可以有效避免不想要的元素（如畸形、水印）。 - **生成步数**：步数越多，细节可能越丰富，但耗时也越长。20-30步是较好的平衡点。 """) # 启动应用 if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860, share=False)

注意：上面的app.py是一个示例框架。Xinference的图片生成API端点 (/v1/images/generations) 和返回的JSON结构可能需要根据你实际部署的liujuan20260223zimage镜像的API文档进行调整。核心逻辑是向http://xinference:9997发送请求并解析返回的图片数据。

1.3 一键启动所有服务

现在，一切就绪。打开终端（命令行），进入liujuan-ai文件夹，执行一条简单的命令：

cd /path/to/your/liujuan-ai docker-compose up -d

-d参数表示在后台运行。执行后，Docker Compose会自动完成以下工作：

从镜像仓库拉取所需的三个镜像（Xinference模型镜像、Gradio镜像、Redis镜像）。
按照docker-compose.yml的配置，创建网络，启动三个容器。
启动顺序是：Redis → Xinference (等待健康检查通过) → Gradio UI。

整个过程可能需要几分钟，特别是首次拉取镜像和Xinference模型加载时。你可以用以下命令查看日志：

# 查看所有服务的日志 docker-compose logs -f # 或者只看Xinference的日志（模型加载进度） docker-compose logs -f xinference

当你看到Xinference日志显示模型加载成功，并且Gradio服务启动成功的消息时，就大功告成了。

2. 使用与验证：你的AI画师上线了

服务启动后，我们来验证一下并开始使用。

2.1 验证服务状态

首先，确认Xinference模型服务是否健康运行。你可以通过检查其日志或直接调用API来验证。

# 方法1：查看容器日志 docker-compose logs xinference | tail -20 # 方法2：在宿主机上调用健康检查API（确保端口映射正确） curl http://localhost:9997/v1/models

如果返回了模型列表信息，说明Xinference服务运行正常。

2.2 访问Web界面

打开你的浏览器，访问以下地址：

http://你的服务器IP:7860

如果是在本地电脑部署，就访问：

http://localhost:7860

你将看到一个简洁美观的Gradio界面，上面有输入框和滑动条。

2.3 生成第一张LiuJuan图片

在“正面提示词”输入框中，输入描述。为了获得最好的LiuJuan风格效果，建议在提示词中包含LiuJuan这个关键词。

例如，你可以输入：

LiuJuan, 一位温婉的古典女子，身着汉服，在月光下的竹林里抚琴，唯美，插画风格

调整一下参数（初学者可以先用默认值），然后点击“生成图像”按钮。

稍等片刻（生成时间取决于模型大小和你的硬件），生成的图片就会显示在右侧预览区了！

2.4 进阶使用技巧

探索提示词：除了LiuJuan，尝试添加更多细节，如“水墨画”、“赛博朋克”、“公主”、“战士”等，观察风格变化。
利用负面提示词：在“负面提示词”框中输入你不希望出现的元素，如“模糊的手”、“多出来的手指”、“水印”，可以显著提升图片质量。
调整参数：
- 生成步数：增加步数（如30）可能让图片细节更丰富，但速度更慢。
- 图片尺寸：模型可能对512x512或768x768等特定尺寸支持更好。非正方形尺寸（如512x768）可以生成长图。

3. 管理、维护与故障排查

3.1 常用管理命令

学会这几个命令，你就能轻松管理你的AI服务了。

# 停止所有服务 docker-compose down # 停止服务并删除所有相关的容器、网络（数据卷通常会保留） docker-compose down -v # 注意：-v 会删除docker-compose.yml中定义的匿名卷，慎用 # 重新启动服务（修改配置后） docker-compose restart # 查看运行中的服务状态 docker-compose ps # 更新镜像并重启（如果镜像有更新） docker-compose pull docker-compose up -d

3.2 常见问题与解决

1. 访问http://localhost:7860打不开页面。

检查服务状态：运行docker-compose ps，确保liujuan_gradio_ui和liujuan_xinference的状态都是Up。
检查端口占用：确认7860和9997端口没有被其他程序占用。可以用netstat -tulpn | grep :7860查看。
查看日志：运行docker-compose logs gradio_ui和docker-compose logs xinference，看是否有错误信息。常见错误是Gradio应用 (app.py) 连接不到Xinference服务，请检查app.py中的XINFERENCE_HOST设置是否正确（在Docker Compose网络内应使用服务名xinference）。

2. 生成图片失败，提示模型未找到或请求错误。

确认模型UID：登录到Xinference容器内，查看启动的模型UID。
```
docker exec -it liujuan_xinference bash # 进入容器后，查看日志或使用xinference命令行工具列出模型 xinference list
```
记下模型的UID，然后修改app.py中的MODEL_UID变量。
检查API端点：查阅你使用的liujuan20260223zimage镜像的文档，确认其提供的文生图API端点路径和请求/响应格式，并相应修改app.py中的generate_image函数。

3. 生成图片速度很慢。

硬件限制：AI图像生成对GPU要求高。如果你在CPU上运行，速度会慢很多。确保你的Docker环境能正确调用GPU（需要安装NVIDIA Docker运行时）。
调整参数：降低steps（生成步数）和width/height（图片尺寸）可以加快生成速度。

4. 如何修改配置（如端口号）？直接修改docker-compose.yml文件中的ports映射即可。例如，想把Web界面端口从7860改为8080，就修改gradio_ui服务的ports为- "8080:7860"。修改后记得运行docker-compose up -d重启服务。

4. 总结

通过这篇教程，我们完成了一个从零到一的完整部署：利用Docker Compose，我们轻松编排了三个核心服务——承载LiuJuan20260223Zimage模型的Xinference推理服务、提供友好交互界面的Gradio Web应用，以及用于优化体验的Redis缓存。你只需要几条命令，就拥有了一个专属的、可随时访问的AI绘画平台。

这种容器化的部署方式优势明显：