Qwen3-4B Instruct-2507部署案例：K8s集群中Qwen3-4B服务化封装实践

想在公司内部快速部署一个专属的、高性能的文本对话AI助手吗？面对复杂的模型部署、资源调度和接口封装，你是否感到无从下手？

本文将带你一步步实践，如何将阿里通义千问的Qwen3-4B-Instruct-2507模型，封装成一个可以在Kubernetes集群中稳定运行、易于扩展的微服务。我们将从Docker镜像构建开始，到K8s资源配置，再到服务暴露，最终实现一个开箱即用、支持流式输出的文本对话API服务。无论你是运维工程师还是后端开发者，都能从中获得一套可直接复用的企业级部署方案。

1. 项目核心价值与设计目标

在开始动手之前，我们先明确这次实践要解决的核心问题以及我们希望达成的目标。

1.1 为什么选择Qwen3-4B-Instruct-2507？

Qwen3-4B-Instruct-2507是阿里通义千问系列中一个非常“务实”的模型。它专注于纯文本任务，移除了视觉、音频等非核心模块，这使得它的“身材”更苗条，推理速度更快。对于企业内部常见的代码辅助、文档生成、知识问答、翻译等场景，它完全够用，而且效率更高，资源消耗更少。选择它作为服务化的对象，性价比非常高。

1.2 本次部署实践的目标

我们的目标不仅仅是“把模型跑起来”，而是要构建一个生产就绪的服务。这意味着我们需要关注以下几点：

  • 服务化：将模型封装成标准的HTTP API，任何应用都能通过网络调用。
  • 资源可控：利用K8s管理GPU/CPU、内存资源，实现弹性伸缩。
  • 高可用：通过多副本部署，避免单点故障。
  • 易于维护：配置集中管理，升级、回滚流程标准化。
  • 性能优化：集成流式输出，减少用户等待时间，提升体验。

接下来，我们就从最基础的容器镜像开始构建。

2. 构建模型服务Docker镜像

将模型和环境打包成Docker镜像是服务化的第一步。这能保证我们的服务在任何K8s节点上运行的环境都是一致的。

2.1 准备模型文件与依赖

首先，我们需要一个工作目录，并准备好模型文件。通常，我们会从ModelScope或Hugging Face Hub下载模型。

# 创建工作目录
mkdir qwen3-4b-service && cd qwen3-4b-service

# 假设模型已下载至本地目录 ./model
# 若需在线下载，可使用Python脚本，这里以准备工作为主

然后，创建我们的核心服务文件 app.py。这个文件将使用FastAPI来提供HTTP接口，并加载Qwen模型。

# app.py
from fastapi import FastAPI, HTTPException
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch
import asyncio
from typing import AsyncGenerator, Optional
import logging

# 配置日志
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

app = FastAPI(title="Qwen3-4B-Instruct API Service")

# 全局变量，用于存储模型和分词器
model = None
tokenizer = None
device = "cuda" if torch.cuda.is_available() else "cpu"

class ChatRequest(BaseModel):
    prompt: str
    max_new_tokens: Optional[int] = 512
    temperature: Optional[float] = 0.7
    stream: Optional[bool] = False

async def load_model():
    """异步加载模型，避免阻塞启动"""
    global model, tokenizer
    model_path = "/app/model"  # Docker容器内的模型路径
    logger.info(f"正在从 {model_path} 加载模型和分词器...")
    
    tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
    model = AutoModelForCausalLM.from_pretrained(
        model_path,
        torch_dtype=torch.float16 if device == "cuda" else torch.float32,
        device_map="auto" if device == "cuda" else None,
        trust_remote_code=True
    ).eval()
    
    if device == "cpu":
        model = model.to(device)
    
    logger.info("模型与分词器加载完毕！")

@app.on_event("startup")
async def startup_event():
    await load_model()

def build_chat_input(prompt: str) -> str:
    """构建符合Qwen Instruct格式的对话输入"""
    messages = [{"role": "user", "content": prompt}]
    # 使用tokenizer内置的聊天模板
    text = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True
    )
    return text

async def generate_stream_response(request: ChatRequest) -> AsyncGenerator[str, None]:
    """流式生成响应"""
    input_text = build_chat_input(request.prompt)
    inputs = tokenizer(input_text, return_tensors="pt").to(device)
    
    streamer = tokenizer.streamer
    generation_kwargs = dict(
        **inputs,
        max_new_tokens=request.max_new_tokens,
        temperature=request.temperature,
        do_sample=request.temperature > 0,
        streamer=streamer,
    )
    
    # 在单独线程中运行生成任务，避免阻塞事件循环
    from threading import Thread
    def generate():
        _ = model.generate(**generation_kwargs)
    
    thread = Thread(target=generate)
    thread.start()
    
    for new_text in streamer:
        yield f"data: {new_text}\n\n"
    
    thread.join()

@app.post("/v1/chat/completions")
async def chat_completion(request: ChatRequest):
    """
    核心对话接口。
    支持流式（stream=True）和非流式输出。
    """
    if model is None or tokenizer is None:
        raise HTTPException(status_code=503, detail="模型未就绪")
    
    if request.stream:
        return StreamingResponse(
            generate_stream_response(request),
            media_type="text/event-stream"
        )
    else:
        # 非流式生成
        input_text = build_chat_input(request.prompt)
        inputs = tokenizer(input_text, return_tensors="pt").to(device)
        with torch.no_grad():
            outputs = model.generate(
                **inputs,
                max_new_tokens=request.max_new_tokens,
                temperature=request.temperature,
                do_sample=request.temperature > 0,
            )
        response = tokenizer.decode(outputs[0][inputs['input_ids'].shape[1]:], skip_special_tokens=True)
        return {"response": response}

@app.get("/health")
async def health_check():
    """健康检查端点"""
    return {"status": "healthy", "model_loaded": model is not None}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

2.2 编写Dockerfile

接下来，我们编写Dockerfile来定义镜像的构建过程。

# Dockerfile
FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime

WORKDIR /app

# 安装系统依赖和Python包
RUN apt-get update && apt-get install -y \
    git \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件并安装Python包
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制模型文件（假设在构建上下文的 model/ 目录下）
COPY model /app/model

# 复制应用代码
COPY app.py .

# 暴露端口
EXPOSE 8000

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD python -c "import requests; requests.get('http://localhost:8000/health', timeout=2)"

# 启动命令
CMD ["python", "app.py"]

requirements.txt 文件内容如下：

fastapi==0.104.1
uvicorn[standard]==0.24.0
transformers==4.36.0
accelerate==0.25.0
torch==2.1.0
pydantic==2.5.0

2.3 构建并测试镜像

在包含 Dockerfile, requirements.txt, app.py 和 model/ 目录的文件夹中，执行构建命令。

# 构建镜像
docker build -t your-registry/qwen3-4b-service:1.0.0 .

# 本地测试运行（确保有GPU）
docker run --gpus all -p 8000:8000 your-registry/qwen3-4b-service:1.0.0

# 测试API
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"prompt": "用Python写一个快速排序函数", "stream": false}'

如果测试成功，你将收到模型生成的代码。接下来，我们将把这个镜像推送到私有仓库，并准备在K8s中部署。

3. 编写Kubernetes部署清单

现在进入核心环节：编写K8s的YAML配置文件，将我们的服务部署到集群中。

3.1 创建命名空间与配置

首先，为我们的AI服务创建一个独立的命名空间，便于管理。

# 1-namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: ai-services

3.2 配置模型服务部署（Deployment）

这是最关键的配置文件，定义了如何运行我们的Pod副本。

# 2-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: qwen3-4b-instruct
  namespace: ai-services
spec:
  replicas: 1  # 初始副本数，可根据GPU资源调整
  selector:
    matchLabels:
      app: qwen3-4b-instruct
  template:
    metadata:
      labels:
        app: qwen3-4b-instruct
    spec:
      # 节点选择器：确保Pod调度到有GPU的节点
      nodeSelector:
        accelerator: nvidia-gpu
      containers:
      - name: model-server
        image: your-registry/qwen3-4b-service:1.0.0  # 替换为你的镜像地址
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8000
          name: http
        resources:
          limits:
            # 重要：申请GPU资源，这里是1张GPU卡
            nvidia.com/gpu: 1
            memory: "12Gi"
            cpu: "4"
          requests:
            nvidia.com/gpu: 1
            memory: "10Gi"
            cpu: "2"
        env:
        - name: CUDA_VISIBLE_DEVICES
          value: "0"
        # 存活探针，检查服务是否健康
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 120  # 模型加载需要时间，延迟长一些
          periodSeconds: 30
          failureThreshold: 3
        # 就绪探针，检查服务是否准备好接收流量
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 150
          periodSeconds: 20
        volumeMounts:
        - name: model-cache
          mountPath: /app/model
          readOnly: true
      # 如果模型文件很大，可以考虑使用持久化卷或Init Container从对象存储下载
      # 这里示例使用一个空的目录卷
      volumes:
      - name: model-cache
        emptyDir: {}

关键点说明：

  1. nodeSelector：确保Pod被调度到带有 accelerator: nvidia-gpu 标签的GPU节点。
  2. resources.limits：明确申请1张GPU卡，以及相应的CPU和内存。这是K8s调度和管理的依据。
  3. 探针（Probes）：livenessProbe 确保不健康的容器被重启；readinessProbe 确保流量只被发送到已准备好的Pod。

3.3 创建服务（Service）暴露内部访问

Deployment管理了Pod，但Pod的IP会变。我们需要一个稳定的Service来作为内部访问入口。

# 3-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: qwen3-4b-service
  namespace: ai-services
spec:
  selector:
    app: qwen3-4b-instruct
  ports:
  - port: 8000        # Service对外暴露的端口
    targetPort: 8000  # 容器端口
    protocol: TCP
    name: http
  type: ClusterIP     # 默认类型，仅在集群内部可访问

3.4 （可选）创建Ingress暴露外部访问

如果想让集群外的用户也能访问，需要配置Ingress。这里以Nginx Ingress为例。

# 4-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: qwen3-4b-ingress
  namespace: ai-services
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600" # 流式响应需要更长的超时时间
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
spec:
  ingressClassName: nginx
  rules:
  - host: ai-api.yourcompany.com  # 替换为你的域名
    http:
      paths:
      - path: /qwen
        pathType: Prefix
        backend:
          service:
            name: qwen3-4b-service
            port:
              number: 8000

4. 部署与验证

所有配置文件准备就绪后，我们就可以在K8s集群中进行部署了。

4.1 应用K8s配置

使用 kubectl apply 命令依次应用配置文件。

# 切换到你的K8s集群上下文
kubectl config use-context your-cluster-context

# 应用所有配置
kubectl apply -f 1-namespace.yaml
kubectl apply -f 2-deployment.yaml
kubectl apply -f 3-service.yaml
# 如果需要外部访问，再应用ingress
# kubectl apply -f 4-ingress.yaml

4.2 监控部署状态

部署后，需要观察Pod是否成功启动，这通常需要几分钟，因为要下载镜像和加载大模型。

# 查看命名空间下的所有资源
kubectl get all -n ai-services

# 重点关注Pod的状态
kubectl get pods -n ai-services -w

# 查看Pod的详细日志，特别是模型加载过程
kubectl logs -f deployment/qwen3-4b-instruct -n ai-services -c model-server

# 查看Pod调度和资源情况
kubectl describe pod -l app=qwen3-4b-instruct -n ai-services

当Pod状态变为 Running，并且就绪探针（READY 列为 1/1）通过后，说明服务已经就绪。

4.3 测试服务接口

服务启动后，我们可以在集群内部进行测试。

# 首先，在集群内临时启动一个测试Pod
kubectl run curl-test --image=curlimages/curl -n ai-services -it --rm -- /bin/sh

# 进入测试Pod的shell后，执行curl命令测试
curl -X POST http://qwen3-4b-service.ai-services.svc.cluster.local:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"prompt": "解释一下什么是Kubernetes", "stream": false}'

# 测试流式接口
curl -X POST http://qwen3-4b-service.ai-services.svc.cluster.local:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"prompt": "写一首关于秋天的五言诗", "stream": true}'

如果一切正常，你将收到模型的文本回复。对于流式接口，你会看到数据分块返回。

5. 生产环境进阶考量

基础的部署完成后，为了满足生产环境的要求，我们还需要考虑以下几个方面。

5.1 模型文件管理

上述例子中模型文件被打包进了镜像，这会导致镜像巨大（>8GB），推送和拉取都很慢。更好的做法是：

  • 使用Init Container：在Pod启动时，从对象存储（如S3、MinIO）或网络存储（如NFS、PVC）下载模型文件到共享卷。
  • 使用持久化卷（PVC）：将模型存储在高速网络存储上，多个Pod副本可以共享只读模型文件。

5.2 自动伸缩（HPA）

根据请求量自动调整Pod副本数。由于GPU资源昂贵，横向扩展（增加Pod）需要更多GPU卡，通常结合集群GPU资源池和队列系统来设计。对于CPU/内存，可以配置HPA。

# 5-hpa.yaml (示例，GPU HPA需要自定义指标)
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: qwen3-4b-hpa
  namespace: ai-services
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: qwen3-4b-instruct
  minReplicas: 1
  maxReplicas: 4 # 最大副本数受限于GPU数量
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

5.3 监控与日志

  • 监控：利用Prometheus采集容器的GPU使用率、显存占用、请求延迟、QPS等指标。可以通过nvidia-dcgm-exporter暴露GPU指标。
  • 日志：确保应用日志输出到标准输出（stdout/stderr），方便K8s的kubectl logs命令查看，并集成EFK或Loki等日志收集系统。

5.4 安全与网络策略

  • API密钥认证：在FastAPI应用中集成API Key验证中间件。
  • 网络策略（NetworkPolicy）：限制只有特定的命名空间或Pod可以访问该服务。
  • TLS终止：在Ingress层面配置HTTPS，保证数据传输安全。

6. 总结

通过以上步骤，我们成功地将Qwen3-4B-Instruct-2507模型封装成了一个Kubernetes微服务。我们回顾一下关键路径：

  1. 服务封装：使用FastAPI编写了支持流式和非流式输出的HTTP API，这是服务化的基础。
  2. 容器化：通过Dockerfile将模型、环境、代码打包成标准镜像，解决了环境一致性问题。
  3. K8s编排：利用Deployment定义服务运行方式，使用Service提供稳定内部访问，通过Ingress（可选）暴露给外部，并借助资源声明、探针等机制保障了服务的可靠性与可观测性。
  4. 生产就绪：讨论了模型文件管理、自动伸缩、监控日志和安全等进阶话题，为实际生产部署提供了思路。

这套方案的优势在于标准化和可扩展性。一旦这个模式跑通，你可以很容易地将其他大模型（如LLaMA、ChatGLM等）以同样的方式部署到你的K8s集群中，快速构建起属于自己或企业的AI服务矩阵。

部署过程中最可能遇到的挑战是GPU资源调度和大镜像/模型文件的管理。确保你的K8s集群正确安装了NVIDIA设备插件，并且规划好高效的镜像仓库和模型文件存储方案。

现在，你的高性能文本对话AI服务已经在K8s集群中蓄势待发，随时准备处理来自各业务系统的调用请求了。

获取更多AI镜像

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

Logo
脑启社区

脑启社区是一个专注类脑智能领域的开发者社区。欢迎加入社区，共建类脑智能生态。社区为开发者提供了丰富的开源类脑工具软件、类脑算法模型及数据集、类脑知识库、类脑技术培训课程以及类脑应用案例等资源。

更多推荐

cover

医学交叉会议！EI检索！2026年人工智能与健康信息学国际学术会议（AIHI 2026）

avatar 脑启社区
cover

图解人工智能（98）人工智能前沿-走向未来

avatar 脑启社区
cover

人形机器人端到端学习及实现的技术途径：Optimus的纯视觉BEV+Transformer方案、RT-2模型跨模态迁移能力测试（上）

avatar 脑启社区