多模態(tài)開(kāi)發(fā)踩坑實(shí)錄
你是不是也遇到這種情況：代碼寫(xiě)完了、跑起來(lái)也沒(méi)報(bào)錯(cuò)，但模型就是“不看圖”？別急，這事兒很常見(jiàn)——多模態(tài)開(kāi)發(fā)不難，難在模型是否真支持多模態(tài)。本文用最簡(jiǎn)單的方式，帶你把“文字+圖片”的多模態(tài)對(duì)話(huà)跑起來(lái)，并告訴你常見(jiàn)坑怎么避。
先把小坑填上：Lombok 報(bào)錯(cuò)這樣一鍵解決
如果你在跑 LangChain4j 的對(duì)話(huà) Demo 時(shí)，控制臺(tái)提示“找不到符號(hào)”的 Lombok 錯(cuò)誤，通常是 IDEA 注解處理器沒(méi)配好。
圖片
上圖：典型的 Lombok 報(bào)錯(cuò)提示
解決方法：
? 打開(kāi) IDEA 設(shè)置 → Annotation Processors
? 勾選 Enable annotation processing
? 改為“使用項(xiàng)目中的 Lombok”
上圖：IDEA 注解處理器正確姿勢(shì)
多模態(tài)到底是啥？為什么重要
? 多模態(tài)=同時(shí)處理文字、圖片、音頻、視頻、PDF 等多種數(shù)據(jù)。
? 典型場(chǎng)景：看圖回答、讀簡(jiǎn)歷提要、解析表格截圖、對(duì) PDF 提問(wèn)、聽(tīng)音頻寫(xiě)總結(jié)等。
上圖：多模態(tài)能理解多種輸入并輸出文本/圖片等
LangChain4j 支持哪些多模態(tài)類(lèi)型
在官方文檔的多模態(tài)章節(jié)可以看到支持情況：
? 用戶(hù)消息可攜帶文本、圖片、音視頻、PDF 等多種內(nèi)容
? 能不能用，關(guān)鍵看“底層模型是否支持”
? 文檔地址（以實(shí)測(cè)為準(zhǔn)）：https://docs.langchain4j.info/tutorials/chat-and-language-models#%E5%A4%9A%E6%A8%A1%E6%80%81
上圖：LangChain4j 多模態(tài)類(lèi)型示意
實(shí)戰(zhàn)：給對(duì)話(huà)加一張圖，讓模型“看圖說(shuō)話(huà)”
我們先寫(xiě)一個(gè)能接收自定義 UserMessage 的方法：
public String chatWithMessage(UserMessage userMessage) {
ChatResponse chatResponse = qwenChatModel
.chat(userMessage);
AiMessage aiMessage = chatResponse.aiMessage();
log.info("AI 輸出：{}", aiMessage.toString());
return aiMessage.text();
}然后寫(xiě)個(gè)單測(cè)，發(fā)一張圖片進(jìn)去：
@Test
void chatWithMessage() {
UserMessage userMessage = UserMessage
.from(
TextContent.from("描述圖片"),
ImageContent.from("https://it666.chat/images/avatar.jpg")
);
aiCodeHelper.chatWithMessage(userMessage);
}運(yùn)行效果如下：
上圖：用圖片做輸入的單測(cè)結(jié)果
為什么沒(méi)生效？關(guān)鍵原因在“模型不支持”
如果你用的是 qwen-max，可能會(huì)發(fā)現(xiàn)：它并不能直接看圖。這不是代碼問(wèn)題，而是“模型能力沒(méi)開(kāi)多模態(tài)”。
這點(diǎn)非常關(guān)鍵：
? 框架會(huì)幫你把文本+圖片打包發(fā)出去
? 但如果模型不支持圖片輸入，它就看不到圖，回答只能按文本來(lái)
可以參考 LangChain4j 的能力支持表（但務(wù)必以實(shí)際測(cè)試為準(zhǔn)）：https://docs.langchain4j.dev/integrations/language-models/
上圖：不同模型的能力差異很大，需實(shí)測(cè)
選型建議：想要“看圖”，優(yōu)先選這些模型
實(shí)測(cè)優(yōu)先考慮（不同廠商地域/版本差異較大，需自己驗(yàn)證）：
? OpenAI 家族：gpt-4o / gpt-4o-mini（圖像理解較穩(wěn)定）
? Azure OpenAI：對(duì)應(yīng)的 4o 系列
? Qwen：Qwen-VL 系列（區(qū)分是否開(kāi)放接口）
? Google：Gemini 1.5 Flash / Pro（區(qū)域與配額限制較多）
注意點(diǎn)：
? 先查清楚“是否支持圖像輸入”和“最大圖片尺寸/大小”
? URL 必須可公網(wǎng)訪問(wèn)，或使用字節(jié)流上傳
? SDK/依賴(lài)版本需匹配，LangChain4j 要跟后端模型 SDK 對(duì)齊
常見(jiàn)坑與避坑清單（強(qiáng)烈建議收藏）
? 模型能力不一致：同一品牌不同型號(hào)能力差別大，別想當(dāng)然。先跑最小可用 Demo。
? 圖片不可訪問(wèn)：本地路徑/私網(wǎng)地址不行，換公網(wǎng) URL 或上傳字節(jié)流。
? 圖片太大：超限會(huì)被靜默壓縮或拒絕，提前做壓縮或限制尺寸。
? 超時(shí)/重試：圖片+文本耗時(shí)更長(zhǎng)，調(diào)大超時(shí)并添加重試策略。
? 版本兼容：LangChain4j 版本與底層 SDK/依賴(lài)要匹配，升級(jí)要看 Release Note。
? 日志與可觀測(cè)：把請(qǐng)求/響應(yīng)元數(shù)據(jù)打印出來(lái)（別打全量敏感內(nèi)容），方便排錯(cuò)。
小結(jié)
? 多模態(tài)不難，難在“模型要真支持”。先跑通最小閉環(huán)，再談業(yè)務(wù)場(chǎng)景。
? LangChain4j 已能優(yōu)雅地傳遞多模態(tài)輸入，但要結(jié)合“支持圖像的模型”一起用。
? 建議你把本文的 Demo 跑起來(lái)，再換成具備圖像理解能力的模型做實(shí)測(cè)。
