跳至主要內容

第1944篇：本地化部署的Qwen系列——Spring AI集成国产开源模型实战

老张2026/4/30大约 8 分钟

第1944篇：本地化部署的Qwen系列——Spring AI集成国产开源模型实战

自从Qwen2.5发布以后，我们团队内部有几个项目陆续从GPT-4o切到了Qwen本地部署。原因很实际：数据不能出境，成本要控制，而且Qwen在中文理解上确实比GPT强不少。

这篇文章把我们整个集成过程里的关键节点和踩过的坑都写出来。不讲概念，讲怎么真正把它用起来。

为什么选Qwen，而不是其他国产模型

这个问题在团队里也讨论过。主要考量点：

开源协议：Qwen系列大部分用的是Apache 2.0协议，商用没有障碍。相比之下有些国产模型的开源协议有商用限制，要仔细看。

模型规模选择：Qwen2.5系列有从0.5B到72B的完整梯队。0.5B/1.5B可以跑在普通服务器上做轻量任务；7B是性能和成本的平衡点；72B接近GPT-4o的水平。根据任务选对模型规格，是控制成本的关键。

工具调用能力：Qwen2.5-Instruct系列原生支持Function Calling和JSON输出，这对我们做AI Agent很重要。我测试过几个国产模型，有些工具调用能力差距很明显。

社区活跃度：阿里的Qwen社区更新比较勤，出问题能找到解决方案的概率更高。

部署方案选择

本地部署有几种方案，各有适用场景：

Ollama（开发环境首选）：最简单，一行命令拉起来，适合本地开发测试。接口是OpenAI兼容的，切换几乎无感。但生产上用Ollama要注意并发能力比较弱。

vLLM（生产推荐）：专门为生产部署设计，支持连续批处理（continuous batching），高并发下吞吐量显著更好。支持OpenAI兼容API，Spring AI可以直接对接。

llama.cpp：CPU推理为主，适合没有GPU的环境，速度慢但部署成本极低。Qwen的GGUF格式模型可以直接跑。

我们生产上用的是vLLM，下面重点讲这条路线。

vLLM部署Qwen2.5

先确认硬件需求（以Qwen2.5-7B-Instruct为例）：

  • 显存需求：float16精度约14GB，4-bit量化约4-5GB
  • 推荐GPU：单卡A10 24GB可以跑7B全精度，两张3090也行

启动命令：

# 以float16精度启动Qwen2.5-7B-Instruct
python -m vllm.entrypoints.openai.api_server \
  --model /models/Qwen2.5-7B-Instruct \
  --served-model-name qwen2.5-7b \
  --dtype float16 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.90 \
  --port 8000 \
  --host 0.0.0.0 \
  --trust-remote-code

# 如果显存不够，用AWQ量化版本
python -m vllm.entrypoints.openai.api_server \
  --model /models/Qwen2.5-7B-Instruct-AWQ \
  --served-model-name qwen2.5-7b-awq \
  --quantization awq \
  --dtype float16 \
  --max-model-len 32768 \
  --port 8000

验证是否正常启动：

curl http://localhost:8000/v1/models
# 应该返回模型列表

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-7b",
    "messages": [{"role": "user", "content": "你好，简单介绍一下你自己"}],
    "temperature": 0.7
  }'

Spring AI集成Qwen

vLLM暴露的是OpenAI兼容API，Spring AI的OpenAI适配器可以直接用，只需要改一下base URL：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>1.0.0-M6</version>
</dependency>

配置文件：

spring:
  ai:
    openai:
      # 指向本地vLLM服务
      base-url: http://your-gpu-server:8000
      # vLLM的API key可以随意填，它不校验
      api-key: "not-needed"
      chat:
        options:
          model: qwen2.5-7b
          temperature: 0.7
          max-tokens: 4096

基本使用和GPT没什么差别：

@Service
public class QwenChatService {

    @Autowired
    private ChatClient chatClient;

    public String chat(String userMessage) {
        return chatClient.prompt()
            .user(userMessage)
            .call()
            .content();
    }

    public String chatWithSystem(String systemPrompt, String userMessage) {
        return chatClient.prompt()
            .system(systemPrompt)
            .user(userMessage)
            .call()
            .content();
    }
}

如果你需要同时配置多个模型（比如GPT和Qwen各管一块业务），需要手动创建Bean：

@Configuration
public class MultiModelConfig {

    @Bean("qwenChatClient")
    public ChatClient qwenChatClient() {
        OpenAiApi qwenApi = OpenAiApi.builder()
            .baseUrl("http://your-gpu-server:8000")
            .apiKey("not-needed")
            .build();

        OpenAiChatModel qwenModel = OpenAiChatModel.builder()
            .openAiApi(qwenApi)
            .defaultOptions(OpenAiChatOptions.builder()
                .model("qwen2.5-7b")
                .temperature(0.7)
                .maxTokens(4096)
                .build())
            .build();

        return ChatClient.builder(qwenModel).build();
    }

    @Bean("gptChatClient")
    public ChatClient gptChatClient() {
        // 标准GPT配置，从环境变量读取API key
        OpenAiApi gptApi = OpenAiApi.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .build();

        OpenAiChatModel gptModel = OpenAiChatModel.builder()
            .openAiApi(gptApi)
            .defaultOptions(OpenAiChatOptions.builder()
                .model("gpt-4o")
                .temperature(0.7)
                .build())
            .build();

        return ChatClient.builder(gptModel).build();
    }
}

Qwen的工具调用集成

Qwen2.5-Instruct支持OpenAI格式的Function Calling，但有一些细节差异要注意。

定义工具：

@Component
public class BusinessTools {

    @Tool(description = "查询指定客户的订单列表，返回最近N条订单记录")
    public List<Order> queryOrders(
            @ToolParam(description = "客户ID") String customerId,
            @ToolParam(description = "查询条数，默认10") Integer limit) {

        int queryLimit = limit != null ? limit : 10;
        return orderRepository.findByCustomerId(customerId,
            PageRequest.of(0, queryLimit, Sort.by("createTime").descending()));
    }

    @Tool(description = "获取商品库存信息，传入商品SKU列表")
    public Map<String, Integer> checkInventory(
            @ToolParam(description = "商品SKU列表，用逗号分隔") String skuList) {

        List<String> skus = Arrays.asList(skuList.split(","));
        return inventoryService.batchQuery(skus);
    }
}

带工具的对话：

@Service
public class QwenAgentService {

    @Autowired
    @Qualifier("qwenChatClient")
    private ChatClient qwenChatClient;

    @Autowired
    private BusinessTools businessTools;

    public String processBusinessQuery(String userQuery) {
        return qwenChatClient.prompt()
            .system("""
                你是一个业务助手，可以查询订单和库存信息。
                在回答用户问题前，优先使用工具获取最新数据。
                回答要简洁准确，用中文回复。
                """)
            .user(userQuery)
            .tools(businessTools)
            .call()
            .content();
    }
}

Qwen工具调用的一个坑：Qwen的工具调用有时候会出现"假工具调用"——模型在回复文本里直接写出了工具调用的格式，而不是真正触发Function Call。这通常是提示词写法的问题，Qwen对工具使用场景的理解需要更明确的引导。

解决方案是在system prompt里加强工具使用的指引：

private static final String TOOL_SYSTEM_PROMPT = """
    你有以下工具可以使用，当用户问到需要实时数据的问题时，必须使用工具获取数据，不要凭记忆回答：
    
    工具使用规则：
    1. 查询订单相关问题 → 使用 queryOrders 工具
    2. 查询库存相关问题 → 使用 checkInventory 工具
    3. 如果一个问题需要多个信息，按顺序分别调用工具
    4. 禁止在回复中直接编造数据
    """;

中文场景的提示词优化

Qwen在中文任务上有些独特的优势和需要注意的地方。

优势：中文理解更自然

Qwen理解中文口语、方言词汇、网络用语的能力比GPT好。比如"帮我把这个整理一下"这种模糊表达，Qwen通常能更准确地推断用户意图。

需要注意：结构化输出的稳定性

在严格JSON输出场景，Qwen7B有时候会在JSON前后加多余的说明文字。解决方案是用JSON模式强制：

public <T> T extractStructured(String prompt, Class<T> responseType) {
    // 方法一：使用Spring AI的结构化输出转换
    return qwenChatClient.prompt()
        .user(prompt)
        .call()
        .entity(responseType);
}

// 或者方法二：在提示词里强制约束
public String extractJson(String content, String jsonSchema) {
    String prompt = String.format("""
        请从以下内容中提取信息，严格按照JSON格式输出，不要输出任何其他内容，不要有代码块标记：
        
        JSON结构：
        %s
        
        内容：
        %s
        """, jsonSchema, content);

    return qwenChatClient.prompt()
        .user(prompt)
        .options(OpenAiChatOptions.builder()
            .responseFormat(new ResponseFormat(ResponseFormat.Type.JSON_OBJECT))
            .build())
        .call()
        .content();
}

多模型路由策略

实际项目里，我们不会所有任务都用同一个模型。搭了一个简单的路由层：

@Service
public class ModelRouter {

    @Autowired
    @Qualifier("qwenChatClient")
    private ChatClient qwenClient;  // 本地Qwen，中文任务

    @Autowired
    @Qualifier("gptChatClient")
    private ChatClient gptClient;   // GPT-4o，需要高质量英文或复杂推理

    @Autowired
    private ChatClient qwenMiniClient;  // Qwen2.5-1.5B，高频简单任务

    public ChatClient route(RoutingContext context) {
        // 数据隐私要求：包含敏感信息必须走本地模型
        if (context.containsSensitiveData()) {
            return qwenClient;
        }

        // 高频简单任务走轻量模型
        if (context.getTaskComplexity() == TaskComplexity.LOW
                && context.getCallFrequency() == Frequency.HIGH) {
            return qwenMiniClient;
        }

        // 中文为主的任务走Qwen
        if (context.getPrimaryLanguage() == Language.CHINESE) {
            return qwenClient;
        }

        // 其他复杂任务走GPT
        return gptClient;
    }
}

@Data
@Builder
public class RoutingContext {
    private boolean containsSensitiveData;
    private TaskComplexity taskComplexity;
    private Frequency callFrequency;
    private Language primaryLanguage;
    private String taskType;

    public enum TaskComplexity { LOW, MEDIUM, HIGH }
    public enum Frequency { LOW, MEDIUM, HIGH }
    public enum Language { CHINESE, ENGLISH, MIXED }
}

性能调优实践

部署上线后我们做了几轮性能调优，记录几个有实质效果的点：

批处理（Batching）：vLLM支持连续批处理，多个请求可以在GPU上同时处理。关键参数是--max-num-seqs（最大并发序列数）和--max-num-batched-tokens。

# 优化并发的启动参数
python -m vllm.entrypoints.openai.api_server \
  --model /models/Qwen2.5-7B-Instruct \
  --max-num-seqs 256 \
  --max-num-batched-tokens 32768 \
  --block-size 16 \
  --gpu-memory-utilization 0.95

KV缓存（Prefix Caching）：如果多个请求共享相同的system prompt（这在实际应用里很常见），开启prefix caching可以显著降低延迟：

--enable-prefix-caching

实测在system prompt较长（1000+ token）的场景下，prefix caching能把首次token延迟降低30-50%。

量化选择：

我们对Qwen2.5-7B做了一个不同量化方案的对比测试，AWQ在大多数任务上和FP16差距在3%以内，但显存需求从14GB降到5GB，这个trade-off很值。

监控和运维

生产上还需要监控体系。vLLM暴露了Prometheus指标：

@Component
public class VllmMonitor {

    @Scheduled(fixedRate = 30000)
    public void collectMetrics() {
        // 拉取vLLM的Prometheus指标
        RestTemplate rt = new RestTemplate();
        String metrics = rt.getForObject("http://gpu-server:8000/metrics", String.class);

        // 解析关键指标
        parseAndReport("vllm:gpu_cache_usage_perc", metrics);
        parseAndReport("vllm:num_requests_running", metrics);
        parseAndReport("vllm:num_requests_waiting", metrics);
        parseAndReport("vllm:avg_generation_throughput_toks_per_s", metrics);
    }

    private void parseAndReport(String metricName, String rawMetrics) {
        // 解析并上报到你的监控系统（Prometheus、InfluxDB等）
    }
}

关键告警指标：

  • gpu_cache_usage_perc > 90%：KV缓存快满了，可能影响新请求
  • num_requests_waiting > 50：排队积压，考虑扩容或增加并发限制
  • avg_generation_throughput_toks_per_s < 50：吞吐下降，检查GPU状态

实际效果和成本对比

部署三个月后，给一个大致的数据参考：

用Qwen2.5-7B替代GPT-4o的中文处理任务，成本降低约85%（算上GPU服务器折旧摊销），延迟从平均2-3秒降到0.5-1秒（因为本地不用走公网）。

当然不是所有场景都适合迁移。我们保留了GPT-4o用于：需要最高质量英文输出的场景、复杂推理任务、以及作为Qwen效果不理想时的fallback。

这种混合策略在实际项目里比较实用，不用All-in一种方案。

编辑此页
最近更新:
贡献者: xiaozhangge