各位做 AI 應(yīng)用開(kāi)發(fā)的讀者朋友大家好。過(guò)去一年多里大模型從單純的“文本對(duì)話(huà)”逐漸走向“多模態(tài)理解與生成”再到“能調(diào)用工具、能操作圖像、能寫(xiě)代碼的智能體”。Qwen千問(wèn)系列模型在這個(gè)過(guò)程中一直是社區(qū)關(guān)注度很高的方向。不少同學(xué)已經(jīng)在嘗試把 Qwen 接入自己的項(xiàng)目但真正落地時(shí)會(huì)發(fā)現(xiàn)模型版本怎么選、本地部署還是走 API、多模態(tài)能力怎么和現(xiàn)有業(yè)務(wù)系統(tǒng)結(jié)合、Embedding 檢索和微調(diào)又該怎么配合使用——這些問(wèn)題如果沒(méi)理清楚很容易卡在 Demo 階段。本文就以“Qwen Live EP2多模態(tài)智能體如何落地”為主題圍繞 Qwen 多模態(tài)能力、本地部署、LoRA 微調(diào)、Embedding 向量檢索、Qwen Code 代碼生成、Java 側(cè) LangChain4j 調(diào)用等方向整理一份可參考的實(shí)戰(zhàn)筆記。全文包含完整代碼示例、配置說(shuō)明和常見(jiàn)排錯(cuò)思路既適合剛接觸 Qwen 的初學(xué)者也適合正在做企業(yè)級(jí) AI 應(yīng)用落地的開(kāi)發(fā)者。1. 多模態(tài)智能體的概念與落地場(chǎng)景1.1 什么是多模態(tài)智能體在繼續(xù)寫(xiě)代碼之前先統(tǒng)一一下概念。“多模態(tài)智能體”可以拆成兩個(gè)層面理解多模態(tài)Multimodal模型不僅能處理文本還能處理圖片、音頻、視頻、文檔等多種輸入。比如你給模型一張產(chǎn)品渲染圖它能描述圖中的物體、風(fēng)格、光影關(guān)系甚至能根據(jù)指令生成編輯后的新圖像。智能體Agent模型不再只是“你問(wèn)我答”的聊天機(jī)器人而是具備任務(wù)拆解、工具調(diào)用、記憶管理、結(jié)果驗(yàn)證能力的執(zhí)行者。它能根據(jù)你的目標(biāo)主動(dòng)調(diào)用函數(shù)、查詢(xún)數(shù)據(jù)庫(kù)、執(zhí)行代碼、操作圖像編輯工具。把兩者結(jié)合起來(lái)多模態(tài)智能體就是一個(gè)“能看、能想、能做”的 AI 工作流輸入可以是圖片加文字指令中間過(guò)程可以調(diào)用檢索服務(wù)、調(diào)用代碼解釋器、調(diào)用圖像生成接口最終輸出可以是文本、代碼、圖像或結(jié)構(gòu)化數(shù)據(jù)。1.2 典型業(yè)務(wù)場(chǎng)景從我接觸到的項(xiàng)目來(lái)看多模態(tài)智能體的落地場(chǎng)景大致集中在以下幾類(lèi)場(chǎng)景典型輸入典型輸出涉及能力電商商品圖批量處理商品白底圖 文本指令場(chǎng)景圖、廣告文案圖像理解、圖像編輯、文本生成文檔智能問(wèn)答PDF/圖片合同 問(wèn)題關(guān)鍵信息抽取、風(fēng)險(xiǎn)提示OCR 理解、RAG 檢索、文本問(wèn)答代碼輔助開(kāi)發(fā)需求描述 項(xiàng)目代碼片段代碼實(shí)現(xiàn)、單元測(cè)試、Review 意見(jiàn)代碼生成、代碼理解企業(yè)知識(shí)庫(kù)助手自然語(yǔ)言提問(wèn)帶引用的答案Embedding 檢索、重排序、文本生成設(shè)計(jì)稿自動(dòng)標(biāo)注UI 設(shè)計(jì)圖 標(biāo)注規(guī)則標(biāo)注 JSON、組件代碼視覺(jué)理解、多模態(tài)生成這些場(chǎng)景都不是單一模型能力能搞定的而是需要“多模態(tài)底座 檢索系統(tǒng) 工具調(diào)用 業(yè)務(wù)邏輯編排”共同完成。這也是為什么我們討論 Qwen 時(shí)不能只盯著對(duì)話(huà)效果還要關(guān)注它的模型矩陣和配套生態(tài)。1.3 為什么選 Qwen 作為落地底座Qwen 系列模型的優(yōu)勢(shì)主要體現(xiàn)在幾個(gè)方面開(kāi)源與商用友好Qwen 提供了多種尺寸的開(kāi)源權(quán)重也有官方 API 服務(wù)。開(kāi)發(fā)者可以根據(jù)成本、性能、數(shù)據(jù)合規(guī)要求靈活選擇。能力覆蓋廣文本生成、代碼生成、數(shù)學(xué)推理、視覺(jué)理解、圖像生成、Embedding 等能力均有對(duì)應(yīng)模型。社區(qū)生態(tài)豐富圍繞 Qwen 的微調(diào)教程、部署方案、LangChain4j 等第三方集成案例非常多遇到問(wèn)題更容易找到參考資料。蒸餾模型可用性強(qiáng)比如 DeepSeek-R1-Distill-Qwen 系列把大模型的推理能力蒸餾到 1.5B、7B、14B 等小模型上讓資源受限的環(huán)境也能跑起來(lái)。當(dāng)然選型時(shí)也要理性看待沒(méi)有“最好的模型”只有“最適合當(dāng)前業(yè)務(wù)約束的模型”。后面我們會(huì)展開(kāi)討論選型策略。2. 環(huán)境準(zhǔn)備與模型選型2.1 運(yùn)行環(huán)境建議本文的實(shí)戰(zhàn)示例會(huì)涉及 Python、Java 兩個(gè)技術(shù)棧以及本地部署和 API 調(diào)用兩種運(yùn)行方式。環(huán)境要求如下組件版本建議說(shuō)明Python3.9 - 3.11用于模型調(diào)用、數(shù)據(jù)處理、微調(diào)腳本Java17運(yùn)行 LangChain4j 集成示例Maven3.8管理 Java 依賴(lài)CUDA11.8 或 12.x本地部署 GPU 推理時(shí)使用Docker20.10可選用于部署 Milvus 向量數(shù)據(jù)庫(kù)Milvus2.3向量存儲(chǔ)與檢索Node.js18可選用于前端 Demo 或其他腳本場(chǎng)景依賴(lài)版本需要根據(jù)你的項(xiàng)目實(shí)際情況調(diào)整本文示例以常見(jiàn)環(huán)境為例重點(diǎn)演示配置思路和代碼結(jié)構(gòu)。2.2 Qwen 模型選型清單目前 Qwen 相關(guān)模型家族很龐大這里只列出落地時(shí)最常用的幾類(lèi)模型/服務(wù)類(lèi)型適用場(chǎng)景落地方式Qwen2.5/2.7B/14B/72B文本大模型通用對(duì)話(huà)、業(yè)務(wù)文本處理API / 本地部署Qwen2.5-VL視覺(jué)語(yǔ)言模型圖像理解、OCR、視頻理解API / 本地部署Qwen2.5-Coder代碼模型代碼生成、代碼補(bǔ)全、測(cè)試生成API / 本地部署Qwen LMGE Edit 2511多模態(tài)圖像編輯模型圖像編輯、3D 相機(jī)控制API / 本地部署Qwen EmbeddingEmbedding 模型語(yǔ)義向量化、知識(shí)庫(kù)檢索API / 本地部署DeepSeek-R1-Distill-Qwen推理蒸餾模型復(fù)雜推理、邏輯拆解本地部署舉例來(lái)說(shuō)如果業(yè)務(wù)是“電商圖片一鍵場(chǎng)景化”優(yōu)先關(guān)注 Qwen LMGE Edit 這類(lèi)多模態(tài)編輯能力。如果業(yè)務(wù)是“企業(yè)內(nèi)部文檔問(wèn)答”優(yōu)先規(guī)劃 Qwen Embedding Milvus Qwen 文本生成模型。如果業(yè)務(wù)是“AI 輔助編程”優(yōu)先使用 Qwen Code 或 Qwen2.5-Coder。如果 GPU 資源有限可以嘗試 DeepSeek-R1-Distill-Qwen-1.5B 這類(lèi)小模型。2.3 本地部署 vs API 調(diào)用先看一張對(duì)比表幫你快速判斷維度本地部署API 調(diào)用數(shù)據(jù)安全數(shù)據(jù)不出內(nèi)網(wǎng)可控性強(qiáng)數(shù)據(jù)經(jīng)過(guò)第三方服務(wù)需評(píng)估合規(guī)硬件成本GPU/A100/H100 或消費(fèi)級(jí)顯卡按 Token 計(jì)費(fèi)彈性成本部署復(fù)雜度較高涉及模型加載、推理服務(wù)、并發(fā)優(yōu)化低官方控制臺(tái)創(chuàng)建 Key 即可可控性可自定義并發(fā)、量化、流式輸出受服務(wù)方限流與版本更新影響迭代速度依賴(lài)自己升級(jí)模型版本官方更新后立即可用我的建議是小規(guī)模驗(yàn)證和原型開(kāi)發(fā)優(yōu)先用 API正式生產(chǎn)且對(duì)數(shù)據(jù)敏感度高的場(chǎng)景再考慮本地部署。也可以采用“混用模式”——核心推理走私有化部署外圍能力例如 Embedding、圖像編輯走 API。3. Qwen 核心能力拆解與快速上手這一節(jié)我們挑幾個(gè)落地時(shí)最能派上用場(chǎng)的能力分別給出最小示例和參數(shù)解釋。3.1 文本生成與對(duì)話(huà)無(wú)論是直接調(diào)用官方 API 還是本地部署文本生成都是最基礎(chǔ)的能力。下面以 OpenAI 兼容接口為例展示如何調(diào)用 Qwen 文本模型。代碼中需要注意base_url、api_key、model三個(gè)參數(shù)的配置。# 文件路徑examples/text_chat.py from openai import OpenAI client OpenAI( # 如果使用本地 vLLM/Ollama 部署這里可以換成 http://localhost:8000/v1 base_urlhttps://your-qwen-endpoint/v1, api_keyyour-api-key, ) response client.chat.completions.create( modelqwen2.5-14b-instruct, messages[ {role: system, content: 你是一名資深 Java 后端工程師擅長(zhǎng)代碼評(píng)審。}, {role: user, content: 請(qǐng)幫我分析下面這段代碼的潛在問(wèn)題\npublic void save(User user) { userDao.save(user); }} ], temperature0.3, max_tokens1024, ) print(response.choices[0].message.content)關(guān)鍵參數(shù)說(shuō)明temperature控制隨機(jī)性。代碼生成、關(guān)鍵業(yè)務(wù)處理建議設(shè)低0.1 - 0.4文案創(chuàng)意類(lèi)可設(shè)高0.7 - 0.9。max_tokens控制最大輸出長(zhǎng)度。注意它計(jì)算的是 Token 數(shù)不是漢字?jǐn)?shù)。stream如需流式輸出打字機(jī)效果設(shè)置為T(mén)rue并按 Streaming 協(xié)議處理。3.2 多模態(tài)圖像理解與編輯多模態(tài)是當(dāng)前 Qwen 落地中最熱的方向。以 Qwen LMGE Edit 2511 為例這類(lèi)模型支持圖像理解、圖像編輯、3D 相機(jī)控制等能力。下面演示一個(gè)“圖像理解 編輯指令”的完整示例。為了便于復(fù)制運(yùn)行我們把圖像轉(zhuǎn)為 Base64 后傳給模型。# 文件路徑examples/multimodal_edit.py import base64 import requests def encode_image(image_path): with open(image_path, rb) as f: return base64.b64encode(f.read()).decode(utf-8) image_base64 encode_image(input_product.png) payload { model: qwen-lmge-edit-2511, messages: [ { role: user, content: [ { type: image_url, image_url: { url: fdata:image/png;base64,{image_base64} } }, { type: text, text: 請(qǐng)把這張商品圖放在一個(gè)簡(jiǎn)約的木質(zhì)桌面上光線(xiàn)保持柔和輸出編輯后的圖片。 } ] } ] } resp requests.post( https://your-qwen-endpoint/v1/multimodal/edit, jsonpayload, headers{Authorization: Bearer your-api-key} ) print(resp.status_code) print(resp.json())如果使用的是本地部署的視覺(jué)語(yǔ)言模型也可以走 vLLM 的 OpenAI 兼容接口model參數(shù)改成實(shí)際的模型名即可。3.3 Embedding 向量化搭配 Milvus 實(shí)現(xiàn)知識(shí)庫(kù)檢索真實(shí)業(yè)務(wù)中多模態(tài)智能體往往需要回答領(lǐng)域知識(shí)問(wèn)題。常見(jiàn)的做法是 RAG檢索增強(qiáng)生成流程如下將文檔切片并調(diào)用 Embedding 模型生成向量。將向量和原文存入 Milvus。用戶(hù)提問(wèn)時(shí)將問(wèn)題向量化并在 Milvus 中檢索最相似的片段。將命中的片段拼到 Prompt 中交給 Qwen 文本模型生成答案。下面先用 Python 演示一段 Embedding 調(diào)用邏輯# 文件路徑examples/embedding_demo.py from openai import OpenAI client OpenAI( base_urlhttps://your-qwen-endpoint/v1, api_keyyour-api-key, ) resp client.embeddings.create( modelqwen-embedding, input[Milvus 是一個(gè)開(kāi)源的向量數(shù)據(jù)庫(kù), Qwen 是阿里開(kāi)源的模型系列] ) vectors [item.embedding for item in resp.data] print(f向量維度: {len(vectors[0])}) print(f生成向量數(shù)量: {len(vectors)})向量維度取決于模型Qwen Embedding 通常輸出 1024 或 1536 維。實(shí)際項(xiàng)目里要把向量寫(xiě)入 Milvus 時(shí)需要保證集合的維度字段和 Embedding 輸出維度一致否則插入會(huì)報(bào)錯(cuò)。下面看完整的 Milvus 寫(xiě)入和檢索示例。# 文件路徑examples/milvus_rag.py from pymilvus import connections, CollectionSchema, FieldSchema, Collection, DataType # 1. 連接 Milvus connections.connect(aliasdefault, hostlocalhost, port19530) # 2. 定義集合字段以 1024 維為例 fields [ FieldSchema(nameid, dtypeDataType.INT64, is_primaryTrue, auto_idTrue), FieldSchema(nametext, dtypeDataType.VARCHAR, max_length2000), FieldSchema(nameembedding, dtypeDataType.FLOAT_VECTOR, dim1024), ] schema CollectionSchema(fieldsfields, description文檔知識(shí)庫(kù)) collection Collection(nameknowledge_base, schemaschema) # 3. 創(chuàng)建索引并使用 IVF_FLAT生產(chǎn)環(huán)境可根據(jù)數(shù)據(jù)量選擇 HNSW collection.create_index( field_nameembedding, index_params{index_type: IVF_FLAT, metric_type: COSINE, params: {nlist: 128}} ) # 4. 寫(xiě)入數(shù)據(jù) docs [ {text: Milvus 支持多種索引類(lèi)型。, embedding: [0.1] * 1024}, {text: Qwen 支持多模態(tài)輸入。, embedding: [0.2] * 1024}, ] collection.insert(docs) collection.flush() # 5. 向量檢索 query_vector [0.15] * 1024 collection.load() results collection.search( data[query_vector], anns_fieldembedding, param{metric_type: COSINE}, limit5, output_fields[text], ) for hits in results: for hit in hits: print(f文本: {hit.entity.get(text)}, 相似度: {hit.distance})生產(chǎn)環(huán)境中需要替換成真實(shí)的 Embedding 向量并考慮數(shù)據(jù)切分策略、索引參數(shù)調(diào)優(yōu)和集合分區(qū)分片。3.4 代碼生成與輔助編程Qwen Code 是面向代碼開(kāi)發(fā)場(chǎng)景的模型適合代碼生成、代碼解釋、單元測(cè)試生成、SQL 編寫(xiě)等任務(wù)。除了直接對(duì)話(huà)還可以通過(guò)“Skills 命令”把它集成到 IDE 或命令行工作流中。下面是一個(gè)使用 Qwen Code 生成單元測(cè)試的示例# 文件路徑examples/code_gen.py from openai import OpenAI client OpenAI( base_urlhttps://your-qwen-endpoint/v1, api_keyyour-api-key, ) prompt 請(qǐng)為下面的 Java 方法生成 JUnit 5 單元測(cè)試 public boolean isAdult(int age) { return age 18; } 要求 1. 覆蓋邊界條件 age17, age18, age19 2. 使用 ParameterizedTest 參數(shù)化測(cè)試 3. 輸出完整代碼 response client.chat.completions.create( modelqwen2.5-coder-14b-instruct, messages[{role: user, content: prompt}], temperature0.2, ) print(response.choices[0].message.content)在真實(shí)的“AI 編程助手”落地中需要把代碼生成模型與倉(cāng)庫(kù)索引、代碼檢索、本地編譯驗(yàn)證結(jié)合起來(lái)而不是簡(jiǎn)單地用對(duì)話(huà)模型生成一整段代碼就完事。后續(xù)我會(huì)單獨(dú)出一篇關(guān)于 Qwen Code 工程化的文章。3.5 LoRA 微調(diào)讓模型適配領(lǐng)域風(fēng)格很多時(shí)候通用模型無(wú)法滿(mǎn)足特定領(lǐng)域的輸出要求例如要求生成特定格式的 JSON。要求輸出帶有企業(yè)術(shù)語(yǔ)口徑。要求模仿特定業(yè)務(wù)場(chǎng)景下的表達(dá)風(fēng)格。這時(shí)可以引入 LoRALow-Rank Adaptation微調(diào)。LoRA 的核心思想是凍結(jié)原模型權(quán)重只訓(xùn)練一小部分低秩矩陣作為增量參數(shù)。優(yōu)點(diǎn)是顯存占用低、訓(xùn)練速度快、模型體積小適合個(gè)人開(kāi)發(fā)者和小型團(tuán)隊(duì)。下面是一個(gè)使用transformerspeft進(jìn)行 LoRA 微調(diào)的簡(jiǎn)化代碼框架。# 文件路徑examples/lora_finetune.py from datasets import load_dataset from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training from trl import SFTTrainer model_name Qwen/Qwen2.5-7B-Instruct # 1. 加載模型與分詞器 model AutoModelForCausalLM.from_pretrained( model_name, load_in_4bitTrue, device_mapauto, ) tokenizer AutoTokenizer.from_pretrained(model_name) tokenizer.pad_token tokenizer.eos_token # 2. 配置 LoRA lora_config LoraConfig( r8, lora_alpha16, lora_dropout0.05, biasnone, task_typeCAUSAL_LM, target_modules[q_proj, k_proj, v_proj, o_proj], ) # 3. 包裝模型 model prepare_model_for_kbit_training(model) model get_peft_model(model, lora_config) # 4. 構(gòu)造訓(xùn)練參數(shù) training_args TrainingArguments( output_dir./qwen-lora-output, per_device_train_batch_size2, gradient_accumulation_steps4, num_train_epochs3, learning_rate2e-4, fp16True, logging_steps10, save_steps500, ) # 5. 加載訓(xùn)練數(shù)據(jù)并使用 SFTTrainer dataset load_dataset(json, data_filestrain.jsonl)[train] trainer SFTTrainer( modelmodel, argstraining_args, train_datasetdataset, tokenizertokenizer, ) trainer.train() trainer.save_model(./qwen-lora-output/final)LoRA 微調(diào)不是萬(wàn)能的它適合風(fēng)格適配和輕量知識(shí)注入無(wú)法替代大規(guī)模全參訓(xùn)練。微調(diào)數(shù)據(jù)質(zhì)量比數(shù)量更重要至少要保證幾十條高質(zhì)量樣本才能看到明顯效果。4. 完整實(shí)戰(zhàn)構(gòu)建一個(gè)多模態(tài)智能體工作流這一節(jié)我們把前面的能力串起來(lái)實(shí)現(xiàn)一個(gè)“商品圖片智能分析與知識(shí)庫(kù)問(wèn)答”多模態(tài)智能體原型。4.1 需求分析假設(shè)我們是一家電商代運(yùn)營(yíng)公司運(yùn)營(yíng)同學(xué)每天要處理大量商品圖片并需要回答類(lèi)似“這個(gè)商品適合什么人群”“競(jìng)品有沒(méi)有類(lèi)似款”“我們知識(shí)庫(kù)里有沒(méi)有這個(gè)品類(lèi)的運(yùn)營(yíng)經(jīng)驗(yàn)”等問(wèn)題。我們要構(gòu)建的工作流如下輸入商品圖片 自然語(yǔ)言問(wèn)題。第一步使用 Qwen 多模態(tài)模型理解圖片內(nèi)容提取關(guān)鍵屬性品類(lèi)、顏色、風(fēng)格、適用場(chǎng)景。第二步將提取的屬性轉(zhuǎn)為 Embedding 向量從 Milvus 中檢索相似商品和運(yùn)營(yíng)經(jīng)驗(yàn)。第三步將圖片理解結(jié)果和檢索結(jié)果合并交給 Qwen 文本模型生成最終回復(fù)。輸出結(jié)構(gòu)化分析結(jié)果 知識(shí)庫(kù)參考 推薦動(dòng)作。整體流程可以拆成如下步驟不用圖畫(huà)用文字描述用戶(hù)上傳圖片 →多模態(tài)理解服務(wù)抽取屬性 →Embedding 向量檢索 →上下文拼接 →LLM 生成最終答案 →返回前端展示。4.2 項(xiàng)目結(jié)構(gòu)multimodal-agent-demo/ ├── python_service/ │ ├── app.py # FastAPI 入口 │ ├── services/ │ │ ├── vision_service.py # 多模態(tài)圖片理解 │ │ ├── embedding_service.py# 向量化服務(wù) │ │ ├── retrieval_service.py# Milvus 檢索 │ │ └── llm_service.py # 文本生成 │ └── requirements.txt ├── java_client/ │ ├── pom.xml # Maven 依賴(lài) │ └── src/main/java/... │ └── RagDemo.java # LangChain4j Milvus 調(diào)用示例 ├── data/ │ └── product_kb.json # 商品知識(shí)庫(kù)測(cè)試數(shù)據(jù) └── README.md4.3 Python 多模態(tài) Agent 服務(wù)我們使用 FastAPI 作為服務(wù)端把多模態(tài)理解、檢索和生成編排起來(lái)。先看依賴(lài)文件# 文件路徑python_service/requirements.txt fastapi0.115.6 uvicorn0.34.0 openai1.57.4 pymilvus2.5.4 python-multipart0.0.20多模態(tài)理解服務(wù)# 文件路徑python_service/services/vision_service.py import base64 from openai import OpenAI class VisionService: def __init__(self, api_key: str, base_url: str, model: str): self.client OpenAI(api_keyapi_key, base_urlbase_url) self.model model def analyze_product_image(self, image_path: str) - dict: with open(image_path, rb) as f: img_base64 base64.b64encode(f.read()).decode(utf-8) messages [ { role: user, content: [ { type: image_url, image_url: {url: fdata:image/jpeg;base64,{img_base64}} }, { type: text, text: 請(qǐng)分析這張商品圖返回 JSON字段包括category品類(lèi)、color主色調(diào)、style風(fēng)格、scene適用場(chǎng)景。只返回 JSON 不要解釋。 } ] } ] response self.client.chat.completions.create( modelself.model, messagesmessages, temperature0.1, response_format{type: json_object}, ) import json content response.choices[0].message.content return json.loads(content)檢索服務(wù)# 文件路徑python_service/services/retrieval_service.py from pymilvus import connections, Collection class RetrievalService: def __init__(self, host: str, port: str, collection_name: str): connections.connect(aliasdefault, hosthost, portport) self.collection Collection(namecollection_name) def search_similar(self, query_vector: list, top_k: int 3) - list: self.collection.load() results self.collection.search( data[query_vector], anns_fieldembedding, param{metric_type: COSINE}, limittop_k, output_fields[text, source], ) return [ {text: hit.entity.get(text), source: hit.entity.get(source), score: hit.distance} for hit in results[0] ]主服務(wù)編排# 文件路徑python_service/app.py import os from fastapi import FastAPI, UploadFile, File from services.vision_service import VisionService from services.embedding_service import EmbeddingService from services.retrieval_service import RetrievalService from services.llm_service import LLMService app FastAPI(titleQwen 多模態(tài)智能體) vision_service VisionService( api_keyos.getenv(QWEN_API_KEY), base_urlos.getenv(QWEN_BASE_URL), modelos.getenv(VISION_MODEL, qwen2.5-vl-7b-instruct), ) embedding_service EmbeddingService( api_keyos.getenv(QWEN_API_KEY), base_urlos.getenv(QWEN_BASE_URL), modelos.getenv(EMBEDDING_MODEL, qwen-embedding), ) retrieval_service RetrievalService( hostos.getenv(MILVUS_HOST, localhost), portos.getenv(MILVUS_PORT, 19530), collection_nameproduct_kb, ) llm_service LLMService( api_keyos.getenv(QWEN_API_KEY), base_urlos.getenv(QWEN_BASE_URL), modelos.getenv(LLM_MODEL, qwen2.5-14b-instruct), ) app.post(/agent/analyze) async def analyze_product(file: UploadFile File(...)): # 保存上傳文件 tmp_path f/tmp/{file.filename} with open(tmp_path, wb) as f: f.write(await file.read()) # 1. 多模態(tài)理解 product_info vision_service.analyze_product_image(tmp_path) # 2. 生成查詢(xún)向量并檢索 query_text f{product_info.get(category)} {product_info.get(style)} {product_info.get(scene)} query_vector embedding_service.generate_embedding(query_text) related_docs retrieval_service.search_similar(query_vector, top_k3) # 3. 拼接上下文生成最終回答 context \n.join([doc[text] for doc in related_docs]) answer llm_service.generate_answer(product_info, context) return { product_info: product_info, related_knowledge: related_docs, answer: answer, }啟動(dòng)命令cd python_service export QWEN_API_KEYyour-api-key export QWEN_BASE_URLhttps://your-qwen-endpoint/v1 export MILVUS_HOSTlocalhost export MILVUS_PORT19530 uvicorn app:app --host 0.0.0.0 --port 8000 --reload4.4 Java 側(cè)集成LangChain4j Milvus 調(diào)用示例在真實(shí)企業(yè)里很多后端不是 Python 而是 Java。如果團(tuán)隊(duì)希望在 Java 微服務(wù)中引入 Qwen Embedding 和 Milvus 檢索可以使用 LangChain4j 這一套庫(kù)。先看 Maven 依賴(lài)!-- 文件路徑j(luò)ava_client/pom.xml -- dependencies dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version1.0.0-beta1/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version1.0.0-beta1/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-milvus/artifactId version1.0.0-beta1/version /dependency /dependencies核心調(diào)用代碼// 文件路徑j(luò)ava_client/src/main/java/RagDemo.java import dev.langchain4j.data.embedding.Embedding; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.openai.OpenAiEmbeddingModel; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.store.embedding.EmbeddingStore; import dev.langchain4j.store.embedding.milvus.MilvusEmbeddingStore; public class RagDemo { public static void main(String[] args) { // 1. 初始化 Qwen Embedding 模型OpenAI 兼容模式 EmbeddingModel embeddingModel OpenAiEmbeddingModel.builder() .apiKey(System.getenv(QWEN_API_KEY)) .baseUrl(System.getenv(QWEN_BASE_URL)) .modelName(qwen-embedding) .build(); // 2. 初始化 Milvus 向量存儲(chǔ) EmbeddingStoreTextSegment embeddingStore MilvusEmbeddingStore.builder() .host(localhost) .port(19530) .collectionName(java_product_kb) .dimension(1024) .build(); // 3. 寫(xiě)入文檔實(shí)際項(xiàng)目中需要先切分文檔 TextSegment segment TextSegment.from(平面磨砂玻璃杯北歐簡(jiǎn)約風(fēng)適合辦公場(chǎng)景。); Embedding embedding embeddingModel.embed(segment).content(); embeddingStore.add(embedding, segment); // 4. 檢索 String query 北歐風(fēng)格 玻璃杯; Embedding queryEmbedding embeddingModel.embed(query).content(); var matches embeddingStore.search(queryEmbedding, 3); for (var match : matches) { System.out.println(相似度: match.score()); System.out.println(文本: match.embedded().text()); } // 5. 將檢索結(jié)果交給 Qwen Chat 模型生成答案 OpenAiChatModel chatModel OpenAiChatModel.builder() .apiKey(System.getenv(QWEN_API_KEY)) .baseUrl(System.getenv(QWEN_BASE_URL)) .modelName(qwen2.5-14b-instruct) .build(); String answer chatModel.generate(根據(jù)以下知識(shí)回答\n match.embedded().text() \n問(wèn)題 query); System.out.println(答案: answer); } }需要說(shuō)明的是LangChain4j 的 API 在版本迭代中變化較快以上示例建立在當(dāng)前常見(jiàn)版本之上。如果你的項(xiàng)目使用了不同版本必須以官方文檔為準(zhǔn)。4.5 運(yùn)行與驗(yàn)證在 Milvus 中創(chuàng)建好product_kb集合后啟動(dòng) Python 服務(wù)再打開(kāi)一個(gè)終端發(fā)送測(cè)試請(qǐng)求curl -X POST http://localhost:8000/agent/analyze \ -F file./data/product.jpg預(yù)期輸出結(jié)構(gòu)如下{ product_info: { category: 水杯, color: 乳白色, style: 北歐簡(jiǎn)約風(fēng), scene: 辦公/居家 }, related_knowledge: [ { text: 平面磨砂玻璃杯北歐簡(jiǎn)約風(fēng)適合辦公場(chǎng)景。, source: product_kb.json, score: 0.86 } ], answer: 根據(jù)圖片分析這個(gè)商品屬于北歐簡(jiǎn)約風(fēng)水杯適合辦公和居家場(chǎng)景。知識(shí)庫(kù)中的類(lèi)似商品運(yùn)營(yíng)經(jīng)驗(yàn)是…… }如果你發(fā)現(xiàn)score普遍偏低比如低于 0.5優(yōu)先檢查 Embedding 模型是否切換正確或者 Milvus 集合的metric_type是否配置成了 COSINE。5. 常見(jiàn)問(wèn)題與排查思路在實(shí)際開(kāi)發(fā)中大家最容易踩到的坑集中在部署、版本、資源、數(shù)據(jù)格式四個(gè)方面。下面整理一個(gè)排查表問(wèn)題現(xiàn)象常見(jiàn)原因解決思路API 調(diào)用返回 404base_url路徑不對(duì)確認(rèn)是否帶/v1后綴檢查模型服務(wù)路由Embedding 維度不匹配Milvus 集合的dim與模型輸出維度不同先打印向量維度再創(chuàng)建集合本地部署 OOM模型參數(shù)量大于顯存使用 4bit 量化、選擇更小模型、開(kāi)啟 CPU offload微調(diào)訓(xùn)練 loss 為 NaN學(xué)習(xí)率過(guò)大、數(shù)據(jù)存在過(guò)長(zhǎng)文本降低學(xué)習(xí)率檢查數(shù)據(jù)長(zhǎng)度和特殊字符圖像理解返回空值圖片格式不支持、base64 編碼錯(cuò)誤統(tǒng)一使用 JPEG/PNG檢查 base64 字符串檢索結(jié)果不相關(guān)未做文檔切分、Embedding 模型未配置按段落切分文檔補(bǔ)充 metadata 過(guò)濾Java 側(cè) LangChain4j 找不到類(lèi)版本兼容問(wèn)題統(tǒng)一用 BOM 管理依賴(lài)版本查看官方 Upgrade Guide另外在本地部署 Qwen 模型時(shí)推薦優(yōu)先嘗試 vLLM 或者 Ollama 這類(lèi)推理加速工具。vLLM 的 OpenAI 兼容接口能極大降低接入成本也能支持流式輸出和并發(fā)請(qǐng)求。6. 最佳實(shí)踐與工程建議6.1 模型服務(wù)與業(yè)務(wù)服務(wù)分離不要把模型推理邏輯直接嵌在業(yè)務(wù)代碼里。推薦單獨(dú)部署一個(gè) Model Service 層對(duì)外提供統(tǒng)一的 API 接口。這樣模型升級(jí)、回滾、并發(fā)擴(kuò)容都不會(huì)影響上層業(yè)務(wù)。建議的服務(wù)分層業(yè)務(wù)層處理用戶(hù)請(qǐng)求、業(yè)務(wù)校驗(yàn)、數(shù)據(jù)組裝。Agent 編排層負(fù)責(zé)任務(wù)拆解、工具調(diào)用、上下文管理。模型服務(wù)層統(tǒng)一封裝多模態(tài)、生成、Embedding 能力?；A(chǔ)設(shè)施層Milvus、Redis、消息隊(duì)列、對(duì)象存儲(chǔ)。6.2 數(shù)據(jù)安全和權(quán)限控制多模態(tài)智能體往往會(huì)接觸到敏感數(shù)據(jù)尤其是企業(yè)內(nèi)部文檔和商品信息。生產(chǎn)環(huán)境必須注意對(duì)上傳圖片做合規(guī)審核防止惡意內(nèi)容進(jìn)入模型。不在 Prompt 中明文傳遞敏感密鑰。模型服務(wù)和外部系統(tǒng)之間使用內(nèi)網(wǎng)或私有網(wǎng)絡(luò)。向量數(shù)據(jù)庫(kù)中的文檔需要按部門(mén)/用戶(hù)做權(quán)限過(guò)濾避免越權(quán)查詢(xún)。記錄完整的請(qǐng)求日志和操作審計(jì)日志便于問(wèn)題追溯。6.3 Prompt 工程與結(jié)果校驗(yàn)多模態(tài)模型和文本模型一樣對(duì) Prompt 非常敏感。經(jīng)驗(yàn)是輸出結(jié)構(gòu)化數(shù)據(jù)時(shí)指定 JSON Schema 并要求“只返回 JSON”。多模態(tài)理解任務(wù)中給出可量化的屬性枚舉減少自由發(fā)揮空間。對(duì)模型結(jié)果做基礎(chǔ)校驗(yàn)例如 JSON 格式校驗(yàn)、字段存在性校驗(yàn)、數(shù)值范圍校驗(yàn)。建立回歸測(cè)試集每次升級(jí)模型或調(diào)整 Prompt 后用固定樣本集跑一遍比較結(jié)果差異。6.4 性能優(yōu)化建議瓶頸點(diǎn)優(yōu)化策略圖像上傳慢壓縮圖片、限制圖片大小、使用對(duì)象存儲(chǔ)臨時(shí)鏈接Embedding 調(diào)用頻繁本地緩存相同文本的向量結(jié)果Milvus 檢索慢增加索引參數(shù)調(diào)優(yōu)考慮分區(qū)控制 top_k 數(shù)量LLM 響應(yīng)慢使用流式輸出、模型并發(fā)部署、緩存常見(jiàn)問(wèn)題答案微調(diào)訓(xùn)練不穩(wěn)定減少 batch size、使用梯度累積、檢查數(shù)據(jù)質(zhì)量6.5 工程化落地清單建議在正式開(kāi)發(fā)前先對(duì)照下面這份清單自檢[ ] 模型選型明確文本、多模態(tài)、Embedding、代碼生成分別用什么模型[ ] 部署方式確定API 還是本地?cái)?shù)據(jù)合規(guī)是否允許[ ] 向量庫(kù)設(shè)計(jì)集合維度、索引類(lèi)型、metric_type 是否確定[ ] Agent 編排方案任務(wù)拆解邏輯是否寫(xiě)死為規(guī)則還是用模型決策[ ] 數(shù)據(jù)流程圖片存儲(chǔ)路徑、文檔切分策略、文本清洗規(guī)則是否明確[ ] 監(jiān)控體系模型調(diào)用耗時(shí)、Token 消耗、檢索召回率是否有監(jiān)控[ ] 應(yīng)急方案模型不可用時(shí)降級(jí)策略、緩存策略是否完善7. 總結(jié)與下一步學(xué)習(xí)路線(xiàn)本文圍繞“Qwen Live EP2多模態(tài)智能體如何落地”這個(gè)主題從概念講到實(shí)戰(zhàn)主要涵蓋了幾個(gè)關(guān)鍵內(nèi)容多模態(tài)智能體的定義、場(chǎng)景和架構(gòu)思路如何根據(jù)業(yè)務(wù)場(chǎng)景選擇 Qwen 模型以及本地部署和 API 調(diào)用的取舍文本生成、多模態(tài)圖像理解與編輯、Embedding 向量化、代碼生成、LoRA 微調(diào)等核心能力的最小可用示例基于 FastAPI Milvus Qwen 的多模態(tài)智能體工作流搭建Java 技術(shù)棧使用 LangChain4j 接入 Milvus 和 Qwen 的參考代碼高頻問(wèn)題排查表和工程落地清單。如果你是從零開(kāi)始建議按照這條路線(xiàn)繼續(xù)學(xué)習(xí)先用 API 跑通 Qwen 的文本對(duì)話(huà)和 Embedding 調(diào)用理解輸入輸出格式。再?lài)L試本地部署一個(gè) 7B 或 14B 模型熟悉 vLLM/Ollama 的使用方法。搭建一個(gè) Milvus 實(shí)例完成從文檔切片、向量寫(xiě)入到檢索的全流程。把多模態(tài)模型接入到同一條鏈路上驗(yàn)證“圖片理解 知識(shí)檢索 文本生成”的工作流。有條件的話(huà)準(zhǔn)備一份小規(guī)模業(yè)務(wù)數(shù)據(jù)集跑一遍 LoRA 微調(diào)觀(guān)察效果變化。多模態(tài)智能體是一個(gè)快速演進(jìn)的領(lǐng)域環(huán)境版本、API 格式、模型能力都在迭代。遇到報(bào)錯(cuò)時(shí)先去確認(rèn)模型名、接口路徑、依賴(lài)版本這三個(gè)最基礎(chǔ)的變量絕大多數(shù)問(wèn)題都能定位到。希望這篇文章能幫你在 Qwen 多模態(tài)落地時(shí)少走一些彎路。如果你也在做類(lèi)似的智能體項(xiàng)目可以在自己的環(huán)境中把示例代碼跑起來(lái)再逐步替換成真實(shí)業(yè)務(wù)數(shù)據(jù)相信很快就能做出一個(gè)可演示、可評(píng)估的原型。