你是不是也遇到這種情況：代碼寫完了、跑起來(lái)也沒報(bào)錯(cuò)，但模型就是“不看圖”？別急，這事兒很常見——多模態(tài)開發(fā)不難，難在模型是否真支持多模態(tài)。本文用最簡(jiǎn)單的方式，帶你把“文字+圖片”的多模態(tài)對(duì)話跑起來(lái)，并告訴你常見坑怎么避。

先把小坑填上：Lombok 報(bào)錯(cuò)這樣一鍵解決

如果你在跑 LangChain4j 的對(duì)話 Demo 時(shí)，控制臺(tái)提示“找不到符號(hào)”的 Lombok 錯(cuò)誤，通常是 IDEA 注解處理器沒配好。

圖片

上圖：典型的 Lombok 報(bào)錯(cuò)提示

解決方法：

? 打開 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 提問、聽音頻寫總結(jié)等。

上圖：多模態(tài)能理解多種輸入并輸出文本/圖片等

LangChain4j 支持哪些多模態(tài)類型

在官方文檔的多模態(tài)章節(jié)可以看到支持情況：

? 用戶消息可攜帶文本、圖片、音視頻、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)類型示意

實(shí)戰(zhàn)：給對(duì)話加一張圖，讓模型“看圖說話”

我們先寫一個(gè)能接收自定義 UserMessage 的方法：

public String chatWithMessage(UserMessage userMessage) {
    ChatResponse chatResponse = qwenChatModel
            .chat(userMessage);

    AiMessage aiMessage = chatResponse.aiMessage();
    log.info("AI 輸出：{}", aiMessage.toString());
    return aiMessage.text();
}

然后寫個(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é)果

為什么沒生效？關(guān)鍵原因在“模型不支持”

如果你用的是 qwen-max，可能會(huì)發(fā)現(xiàn)：它并不能直接看圖。這不是代碼問題，而是“模型能力沒開多模態(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ū)分是否開放接口）

? Google：Gemini 1.5 Flash / Pro（區(qū)域與配額限制較多）

注意點(diǎn)：

? 先查清楚“是否支持圖像輸入”和“最大圖片尺寸/大小”

? URL 必須可公網(wǎng)訪問，或使用字節(jié)流上傳

? SDK/依賴版本需匹配，LangChain4j 要跟后端模型 SDK 對(duì)齊

常見坑與避坑清單（強(qiáng)烈建議收藏）

? 模型能力不一致：同一品牌不同型號(hào)能力差別大，別想當(dāng)然。先跑最小可用 Demo。

? 圖片不可訪問：本地路徑/私網(wǎng)地址不行，換公網(wǎng) URL 或上傳字節(jié)流。

? 圖片太大：超限會(huì)被靜默壓縮或拒絕，提前做壓縮或限制尺寸。

? 超時(shí)/重試：圖片+文本耗時(shí)更長(zhǎng)，調(diào)大超時(shí)并添加重試策略。

? 版本兼容：LangChain4j 版本與底層 SDK/依賴要匹配，升級(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è)。