Qwen1.8B-GPTQ-Int4部署教程：vLLM与Chainlit Docker Compose一体化编排

1. 开篇：为什么选择这个方案？

如果你正在寻找一个轻量、高效、开箱即用的本地大语言模型部署方案，那么你来对地方了。今天要聊的，是把通义千问1.8B的量化版本，通过vLLM这个高性能推理引擎跑起来，再用Chainlit做一个漂亮的Web界面，最后用Docker Compose把它们打包成一个整体。

听起来有点复杂？别担心，我会带你一步步走完。这个方案最大的好处就是“省心”。模型是量化过的，对硬件要求不高；vLLM负责推理，速度快；Chainlit做前端，交互友好；Docker Compose把一切都编排好，你只需要几条命令。

学完这篇教程，你将拥有一个完全在自己掌控下的AI对话助手，可以用于学习、测试，甚至是一些简单的自动化任务。

2. 核心组件介绍：它们各自扮演什么角色？

在动手之前，我们先花几分钟了解一下我们要用到的几个“零件”。这能帮你更好地理解整个流程，万一出了问题也知道该从哪里排查。

2.1 模型：通义千问1.5-1.8B-Chat-GPTQ-Int4

这是今天的主角，一个经过压缩的“小模型”。

• 通义千问1.5-1.8B-Chat：这是阿里推出的一个18亿参数的中英文对话模型。1.8B指的是参数量，对于本地部署来说，这个大小非常友好，在消费级显卡（甚至一些高性能CPU）上都能跑起来。“Chat”意味着它专门针对对话场景进行了优化。
• GPTQ-Int4：这是模型的“瘦身”技术。原始的模型参数是32位浮点数（FP32），非常占内存和显存。GPTQ是一种后训练量化技术，能把参数压缩到4位整数（Int4）。简单说，就是模型的能力基本不变，但体积和运行所需资源大大减少。部署这个版本，你的硬件门槛会低很多。

2.2 推理引擎：vLLM

你可以把vLLM想象成模型的“超级发动机”。

• 它专门为大规模语言模型推理优化过，最大的特点就是快。它用了很多“黑科技”，比如PagedAttention（一种高效管理内存中注意力键值对的技术），能极大地提高吞吐量。
• 它提供了标准的OpenAI兼容的API接口。这意味着，任何能调用ChatGPT API的工具，理论上也能调用我们部署的这个模型，兼容性非常好。

2.3 交互界面：Chainlit

模型跑起来了，我们总得有个方式和它“说话”。Chainlit就是这样一个专门为AI应用设计的Web UI框架。

• 它有点像简化版的Gradio或Streamlit，但更专注于聊天对话场景。
• 它内置了对话历史、代码高亮、文件上传等实用功能，界面美观，几乎不需要写前端代码就能得到一个可用的产品界面。

2.4 编排工具：Docker Compose

这是把上面所有零件组装成一部“整车”的流水线。

• Docker把每个组件（vLLM服务、Chainlit服务）打包成独立的、环境隔离的“容器”。
• Docker Compose则用一个配置文件（docker-compose.yml）定义这些容器如何启动、如何连接网络、如何挂载数据卷。你只需要一个命令，所有服务按正确的顺序和配置启动起来。

好了，理论部分就到这里。接下来，我们进入实战环节。

3. 环境准备与一键部署

我们假设你已经在本地或云服务器上安装好了Docker和Docker Compose。如果还没装，网上有很多教程，搜索“安装Docker和Docker Compose”按照步骤来就行，这里不赘述。

整个部署的核心是一个docker-compose.yml文件。我会先给出完整的文件内容，然后解释关键部分。

在你的项目目录下（比如 ~/qwen-vllm-chainlit），创建一个名为 docker-compose.yml 的文件：

version: '3.8'

services:
  vllm-server:
    image: vllm/vllm-openai:latest
    container_name: qwen-vllm-server
    runtime: nvidia # 如果你使用NVIDIA GPU，需要这个runtime
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ports:
      - "8000:8000"
    volumes:
      - ./models:/app/models
    command: >
      --model /app/models/Qwen1.5-1.8B-Chat-GPTQ-Int4
      --served-model-name Qwen1.8B-Chat
      --api-key token-abc123
      --host 0.0.0.0
      --port 8000
    networks:
      - qwen-net

  chainlit-ui:
    image: chainlit/chainlit:latest
    container_name: qwen-chainlit-ui
    ports:
      - "8080:8000"
    volumes:
      - ./chainlit_app:/app
    working_dir: /app
    environment:
      - OPENAI_API_KEY=token-abc123
      - OPENAI_API_BASE=http://vllm-server:8000/v1
    command: chainlit run app.py
    depends_on:
      - vllm-server
    networks:
      - qwen-net

networks:
  qwen-net:
    driver: bridge

volumes:
  models:
  chainlit_app:

关键点解释：

1. 两个服务：定义了 vllm-server（模型推理服务）和 chainlit-ui（Web界面服务）。
2. GPU支持：vllm-server配置了runtime: nvidia，这是为了使用GPU加速。如果你只用CPU，可以移除runtime和deploy相关配置，vLLM会自动使用CPU，但速度会慢很多。
3. 端口映射：
   • vllm-server: 将容器内的8000端口映射到主机的8000端口。这样你可以通过 http://localhost:8000 直接访问vLLM的API。
   • chainlit-ui: 将容器内的8000端口映射到主机的8080端口。我们的Web界面将通过 http://localhost:8080 访问。
4. 数据卷：
   • ./models:/app/models: 把主机上的 ./models 目录挂载到容器的 /app/models。你需要把下载好的模型文件放到主机的 ./models 目录下。
   • ./chainlit_app:/app: 把主机上的 ./chainlit_app 目录挂载到容器的 /app，这里将存放我们的Chainlit应用代码。
5. 环境变量：chainlit-ui服务通过环境变量 OPENAI_API_BASE 指向了 http://vllm-server:8000/v1。注意这里用的是服务名vllm-server，这是Docker Compose内部网络DNS，两个容器可以互相通过服务名访问。OPENAI_API_KEY 需要和vLLM启动命令中的 --api-key 一致。
6. 依赖关系：chainlit-ui 通过 depends_on 指定在 vllm-server 之后启动。
7. 自定义网络：创建了一个名为 qwen-net 的桥接网络，让两个服务在隔离的网络中通信。

接下来，我们需要准备模型和Chainlit应用代码。

4. 准备模型与Chainlit应用

4.1 下载模型

你需要下载 Qwen1.5-1.8B-Chat-GPTQ-Int4 模型。可以从Hugging Face Model Hub等地方获取。假设你下载后，模型文件目录结构如下：

models/
└── Qwen1.5-1.8B-Chat-GPTQ-Int4/
    ├── config.json
    ├── generation_config.json
    ├── model-00001-of-00002.safetensors
    ├── model-00002-of-00002.safetensors
    ├── model.safetensors.index.json
    ├── quantize_config.json
    └── tokenizer.json

请确保将整个 Qwen1.5-1.8B-Chat-GPTQ-Int4 文件夹放入你项目目录下的 models 文件夹中（与 docker-compose.yml 同级）。

4.2 创建Chainlit应用

在项目根目录下，创建 chainlit_app 文件夹，并在其中创建两个文件：app.py 和 chainlit.md。

chainlit_app/app.py：

import chainlit as cl
from openai import OpenAI

# 配置OpenAI客户端，指向我们本地的vLLM服务
client = OpenAI(
    api_key="token-abc123", # 与docker-compose中设置的一致
    base_url="http://vllm-server:8000/v1" # 注意这里也是服务名
)

@cl.on_chat_start
async def on_chat_start():
    # 会话开始时可以做一些初始化，比如设置系统提示
    system_prompt = "你是一个乐于助人的AI助手，基于通义千问1.8B模型。请用中文友好地回答用户的问题。"
    cl.user_session.set("system_prompt", system_prompt)
    await cl.Message(content="你好！我是基于Qwen1.8B模型的AI助手，有什么可以帮你的吗？").send()

@cl.on_message
async def on_message(message: cl.Message):
    # 获取系统提示
    system_prompt = cl.user_session.get("system_prompt", "")
    
    # 构建消息历史（简单实现，每次只传最新对话）
    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": message.content}
    ]
    
    # 创建一个异步任务来调用API，避免阻塞
    response = await cl.make_async(client.chat.completions.create)(
        model="Qwen1.8B-Chat", # 与vLLM --served-model-name 一致
        messages=messages,
        max_tokens=1024,
        temperature=0.7,
        stream=True # 启用流式输出，体验更好
    )
    
    # 流式响应处理
    msg = cl.Message(content="")
    await msg.send()
    
    async for chunk in response:
        if chunk.choices[0].delta.content is not None:
            await msg.stream_token(chunk.choices[0].delta.content)
    
    await msg.update()

chainlit_app/chainlit.md：

# 欢迎使用 Qwen1.8B 对话助手

这是一个本地部署的通义千问1.8B模型演示界面。

## 功能
- 流畅的中英文对话
- 支持代码解释与生成
- 创意写作与问题解答

## 注意事项
模型为量化版，在复杂推理或知识密集型任务上可能有限制。请享受对话的乐趣！

5. 启动服务与验证

所有文件准备就绪后，打开终端，进入你的项目目录（包含 docker-compose.yml 的目录）。

1. 启动所有服务：

docker-compose up -d

-d 参数表示在后台运行。第一次运行会下载vLLM和Chainlit的Docker镜像，可能需要一些时间。

2. 查看服务日志，确认模型加载成功： 模型加载可能需要几分钟，取决于你的硬件。查看vLLM服务的日志：

docker-compose logs -f vllm-server

当你看到类似下面的日志时，说明模型加载成功，服务已就绪：

INFO 07-28 10:00:00 llm_engine.py:721] Loading model weights...
INFO 07-28 10:01:30 llm_engine.py:825] Model loaded in 90.23 seconds.
INFO 07-28 10:01:30 api_server.py:1273] Started server process [1]
INFO 07-28 10:01:30 api_server.py:1278] Waiting for application startup.
INFO 07-28 10:01:30 api_server.py:1293] Application startup complete.
INFO 07-28 10:01:30 api_server.py:1298] Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

3. 验证服务：

• 验证vLLM API：打开浏览器，访问 http://你的服务器IP:8000/docs，你应该能看到vLLM提供的OpenAI兼容的API文档页面。这是一个好迹象，说明推理服务运行正常。
• 访问Chainlit界面：打开浏览器，访问 http://你的服务器IP:8080。你应该能看到Chainlit的聊天界面。

4. 进行第一次对话： 在Chainlit的Web界面中输入框里，尝试问一些问题，比如：

• “你好，介绍一下你自己。”
• “用Python写一个快速排序函数。”
• “夏天的夜晚有什么特点？”

如果一切正常，你将看到模型生成的流式回复。

6. 常见问题与调试

如果在部署过程中遇到问题，可以按照以下步骤排查：

1. 模型加载失败：

   • 检查模型路径：确认 ./models 目录下是否有正确的模型文件夹，且Docker Compose中挂载的路径无误。
   • 检查日志：仔细查看 docker-compose logs vllm-server 的输出，错误信息通常会明确指出问题，比如文件找不到、格式不支持等。
   • 验证模型文件：确保下载的模型是完整的GPTQ-Int4版本，并且文件没有损坏。

2. Chainlit无法连接vLLM：

   • 检查网络：确保 docker-compose.yml 中两个服务在同一个自定义网络（qwen-net）下。
   • 检查环境变量：确认 chainlit-ui 服务中的 OPENAI_API_BASE 值是否为 http://vllm-server:8000/v1（注意是服务名，不是localhost）。
   • 检查vLLM服务状态：先确认 http://localhost:8000/docs 可以访问。
   • 进入容器调试：可以进入Chainlit容器内部，用curl测试连接：

     docker-compose exec chainlit-ui bash
     curl http://vllm-server:8000/v1/models
     

     应该返回一个包含模型信息的JSON。

3. GPU无法使用：

   • 确认Docker GPU支持：运行 docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi 看是否能输出GPU信息。
   • 检查Compose文件：确保 vllm-server 服务配置了 runtime: nvidia 和 deploy.reservations.devices 部分。
   • 查看vLLM日志：日志中会显示是使用GPU还是CPU。寻找“Using GPU”或“Using CPU”字样。

4. 端口冲突：

   • 如果主机上的8000或8080端口已被占用，可以在 docker-compose.yml 中修改端口映射，例如将 "8000:8000" 改为 "8001:8000"。

7. 总结

回顾一下，我们完成了一件什么事？我们利用Docker Compose，将vLLM推理后端和Chainlit Web前端完美地整合在一起，部署了一个量化版的通义千问1.8B对话模型。

这个方案的优势非常明显：

• 一体化：一个命令启动所有服务，管理方便。
• 资源友好：GPTQ-Int4量化模型大大降低了硬件门槛。
• 性能优异：vLLM提供了业界领先的推理速度。
• 体验良好：Chainlit提供了开箱即用、美观的聊天界面。
• 易于扩展：基于Docker，你可以轻松地将这个部署扩展到其他模型，或者添加更多的服务（比如数据库、缓存）。

你可以在此基础上进行更多探索，例如：

• 修改 chainlit_app/app.py，增加对话历史管理、文件上传处理等功能。
• 调整vLLM的启动参数，如 --max-model-len（上下文长度）、--gpu-memory-utilization等以优化性能。
• 为Chainlit界面添加身份验证、主题定制等。

希望这篇教程能帮助你顺利在本地搭建起属于自己的AI对话助手。动手试试吧，遇到问题多在日志里找线索，社区的资源也很丰富。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。