Đa phương thức không phải một API mới cần học từ đầu. Nó là một hợp đồng dữ liệu: bạn gửi một danh sách các block (văn bản, ảnh, âm thanh), model trả về văn bản, và hóa đơn tính theo token của từng block. Hiểu hợp đồng đó quan trọng hơn nhớ tên lớp trong framework, vì tên lớp đổi giữa các minor version còn hợp đồng thì tương đối ổn định.
Bài này chỉ ra cách LangChain 1.x biểu diễn đầu vào đa phương thức, chỗ nào các provider khác nhau, và chi phí thật của ảnh/PDF. Code dưới đây là khung khái niệm: nó cho thấy luồng dữ liệu, không phải bản copy-paste chạy với mọi provider mà không sửa gì.
Mục lục
Cập nhật 2026
langchain1.4.9 vàlanggraph1.2.20 (Python); TS core 1.3.5, LangGraph TS 1.7.2. Nhánh 1.x đã GA, giấy phép MIT.create_agent(model, tools, middleware)là entry point cho agent.create_react_agentvà các API chuỗi cũ nằm ở packagelangchain-classic, không còn là mặc định.- OpenAI: toàn bộ lineup GPT-6 hiện hành (Astra, Sol, Terra, Luna) nhận text + image đầu vào. Tool calling của Astra và Sol chỉ chạy trên Responses API, không chạy trên Chat Completions.
- Chi phí dài ngữ cảnh: OpenAI tính 2x input/cache và 1.5x output khi request vượt 272K token, áp cho toàn bộ request chứ không phải phần vượt.
Một message, nhiều block
Trong LangChain, đơn vị trao đổi với model vẫn là message: SystemMessage, HumanMessage, AIMessage, ToolMessage. Điều thay đổi khi có đa phương thức là content không còn là chuỗi mà là danh sách các block. Mỗi block có type và payload riêng. Model không “nhìn” ảnh: adapter của provider chuyển block thành JSON mà API của họ chấp nhận, còn model nhận token.
Ba loại block bạn gặp nhiều nhất:
- Text —
{"type": "text", "text": "..."}. Đây là phần prompt thật, và là phần duy nhất bạn kiểm soát chắc chắn về chi phí. - Image — ảnh từ URL công khai, hoặc base64 trong data URL. Ảnh nội bộ, ảnh có dữ liệu khách hàng nên dùng base64 thay vì upload lên một URL công khai.
- Audio — hầu hết model text không nhận trực tiếp. Bạn chuyển âm thanh thành text bằng một model speech-to-text rồi mới đưa vào message; một số provider như Gemini 4 Argon nhận audio trực tiếp.
Đoạn code sau dựng một message gồm hai ảnh và một câu hỏi. Nó dùng shape block mà langchain-openai chuyển thẳng cho Chat Completions. Nếu bạn nâng cấp langchain-core, hãy kiểm tra lại shape: LangChain cũng có content block chuẩn hóa với type: "image", nhưng schema chi tiết phụ thuộc phiên bản đang cài. Đừng trộn hai shape trong cùng một message.
# File: app/multimodal.py
# pip install "langchain==1.4.9" langchain-openai
from pathlib import Path
import base64
from langchain_core.messages import HumanMessage
from langchain_openai import ChatOpenAI
def image_block(path: Path, mime: str = "image/png") -> dict:
data = base64.b64encode(path.read_bytes()).decode("utf-8")
return {
"type": "image_url",
"image_url": {"url": f"data:{mime};base64,{data}"},
}
llm = ChatOpenAI(model="gpt-6.1-terra", temperature=0)
message = HumanMessage(content=[
{"type": "text", "text": "So sánh hai ảnh và chỉ ra ba khác biệt chính."},
image_block(Path("before.png")),
image_block(Path("after.png")),
])
response = llm.invoke([message])
print(response.content)
Hai điểm cần nhớ. Thứ nhất, thứ tự block có ý nghĩa: model đọc tuần tự, nên đặt câu hỏi trước ảnh hay sau ảnh cho kết quả khác nhau trong thực tế. Thứ hai, base64 làm payload phình to; một ảnh 4 MB thành chuỗi khoảng 5,3 MB trong request. Với ảnh chụp màn hình, hãy crop về vùng lỗi thay vì gửi cả màn hình 4K.
Khác biệt provider nằm ở đâu
LangChain che phần lớn khác biệt, nhưng không che hết. Ba chỗ bạn luôn phải kiểm tra trước khi đổi provider:
| Provider | Nhận trực tiếp | Bẫy chính |
|---|---|---|
| OpenAI (GPT-6.x) | Text + image | Tool calling của Astra/Sol cần Responses; surcharge 272K |
| Gemini 4 Argon | Text, image, video, audio, PDF | Không có explicit caching; giá promo hết 2026-11-30 |
| Model speech-to-text | Audio → text | Thêm một bước, thêm một hóa đơn, thêm một chỗ hỏng |
Với OpenAI, block ảnh trong Chat Completions dùng image_url; trong Responses, cấu trúc input khác, nên đừng giả định cùng một shape. Đây là lý do một đoạn code “chạy được với GPT-4o” có thể vỡ khi bạn đổi sang model mới. Hãy coi adapter của provider là thứ có version, không phải lớp trừu tượng bất biến.
Gemini 4 Argon là ngoại lệ đáng chú ý: nó nhận PDF, audio và video trực tiếp, nên bạn có thể bỏ bước OCR và bỏ bước speech-to-text cho một số pipeline. Đổi lại, giá đang là 2 USD/10 USD cho tới hết 2026-11-30, sau đó 4 USD/20 USD. Đừng thiết kế ngân sách dựa trên giá promo.
Với Anthropic, Messages API có shape block riêng cho ảnh và cache có ngưỡng tối thiểu 512 token. Fact base của series chưa xác nhận chi tiết block ảnh của họ, nên hãy đọc docs của SDK anthropic 2.6.0 trước khi viết adapter; đừng suy ra từ code LangChain.
Âm thanh: hai thiết kế, hai chi phí
Có hai cách xử lý âm thanh, và chúng không tương đương:
- Speech-to-text trước, LLM sau. Chạy được với mọi model text, transcript lưu được để audit, và bạn có thể chạy lại phần suy luận mà không tốn tiền phiên âm. Nhược điểm: mất ngữ điệu, mất thông tin người nói nếu model STT không có diarization.
- Audio native. Gemini 4 Argon nhận audio trực tiếp; OpenAI có
gpt-realtime-2.1trênv1/realtimevới giá audio 32 USD vào và 64 USD ra cho mỗi 1M audio token. Đường này đắt hơn đáng kể và khó đánh giá hơn, nhưng giữ được tín hiệu phi văn bản.
Với bài toán meeting summary hoặc ghi chú cuộc gọi, thiết kế thứ nhất thường thắng vì rẻ, dễ test và dễ thay model. Chỉ chọn audio native khi ngữ điệu là một phần của giá trị, ví dụ phát hiện căng thẳng trong cuộc gọi hỗ trợ.
# File: app/transcribe.py
# pip install "openai==3.46.0"
from openai import OpenAI
client = OpenAI()
# ID model STT thay đổi theo provider; kiểm tra docs trước khi pin.
with open("meeting.m4a", "rb") as audio_file:
transcript = client.audio.transcriptions.create(
model="stt-model-hien-hanh",
file=audio_file,
)
print(transcript.text)
Sau khi có transcript, bạn đưa nó vào HumanMessage như một text block. Trong LangChain 1.x, cách gói gọn nhất là một tool nhận đường dẫn file và trả về text, để agent quyết định khi nào cần phiên âm. Dùng decorator @tool từ langchain_core.tools; các tutorial cũ hay import BaseTool từ langchain_community, nhưng đó không phải đường chính trong 1.x — kiểm tra lại nếu bạn đang giữ code cũ.
Chi phí thật của ảnh và PDF
Ảnh được quy đổi thành token theo kích thước và mức chi tiết mà provider chọn, không theo số byte. Vì vậy đừng ước lượng chi phí từ dung lượng file: hãy đọc trường usage của response và đo trên vài mẫu thật. Công thức cụ thể khác nhau giữa các provider và thay đổi; fact base của series không xác nhận con số nào, nên bài này không đưa ra hệ số.
PDF là trường hợp tốn kém nhất trong các pipeline tài liệu. Với provider không nhận PDF trực tiếp, mỗi trang phải render thành ảnh, nghĩa là một hợp đồng 30 trang thành 30 ảnh, và chi phí tỉ lệ với số trang chứ không với lượng chữ. Hai cách giảm chi phí có thật:
- Trích text trước, chỉ gửi ảnh cho trang có bảng hoặc biểu đồ. Bạn cần OCR hoặc parser để biết trang nào là text thuần. Trong tài liệu hành chính, phần lớn trang thường là text thuần, nên số ảnh gửi đi giảm mạnh; hãy đo trên bộ mẫu của bạn thay vì giả định một tỉ lệ.
- Gửi theo lô nhỏ và cache phần đầu. Với prompt hệ thống dài, giữ phần đầu byte-ổn định để provider cache; Anthropic cần tối thiểu 512 token mới cache, dưới ngưỡng đó không có gì được cache.
Còn một bẫy nữa: request vượt 272K token trên OpenAI bị tính 2x cho input và cache, 1.5x cho output, áp cho toàn bộ request. Nếu bạn nhồi 40 ảnh vào một lần gọi, bạn có thể vượt ngưỡng và trả gấp đôi cho cả phần text. Hãy chẻ thành nhiều lần gọi nhỏ, hoặc dùng batch 50% cho tác vụ không cần realtime.
LangChain hay gọi SDK trực tiếp?
Đây là câu hỏi bị đặt sai thường xuyên. LangChain không làm model thông minh hơn; nó chuẩn hóa transport và cung cấp vòng lặp agent. Giá trị thật nằm ở chỗ đổi provider, thêm middleware và nối tool mà không viết lại toàn bộ ứng dụng.
| Tình huống | Chọn | Vì sao |
|---|---|---|
| Một provider, một pipeline tuyến tính | SDK trực tiếp | Ít dependency, kiểm soát streaming và tham số provider |
| Nhiều provider, có fallback | LangChain | Adapter và message chuẩn hóa giảm code rẽ nhánh |
| Agent có tool, cần phê duyệt | LangChain + LangGraph | Middleware, interrupt, checkpointer có sẵn |
| Cần latency thấp, ít bước | SDK trực tiếp | Bỏ được một lớp trừu tượng và một lớp debug |
Một quy tắc thực dụng: nếu hàm Python 20 dòng giải quyết được, đừng dựng agent. Đa phương thức chỉ là định dạng input; phần lớn ứng dụng đọc hóa đơn, chấm bài, hay kiểm tra ảnh sản phẩm không cần vòng lặp agent, chỉ cần một lần gọi model kèm vài tool xác định.
Pitfall thường gặp
- Log nguyên payload base64. Log 5 MB ảnh cho mỗi request làm phình storage và làm lộ dữ liệu. Log hash, kích thước, và loại block; chỉ lưu ảnh trong bucket có kiểm soát truy cập.
- Giả định mọi model đọc PDF. Chỉ Gemini 4 Argon nhận PDF trực tiếp trong các model đang xét. Với provider khác, PDF là bài toán render ảnh.
- Retry mà không idempotent. Một request ảnh bị timeout có thể đã được tính tiền. Dùng key theo
(tenant, request_id)và kiểm tra usage trước khi gửi lại. - Trộn block shape.
image_urlvà block chuẩn hóaimagekhông tương đương. Chọn một shape theo phiên bảnlangchain-corevà viết test nhỏ xác nhận adapter chấp nhận nó. - Đổi model không đổi prompt. Model mới có thể cần mô tả ảnh ngắn hơn hoặc dài hơn. Giữ một tập eval 20–30 mẫu và chạy lại trước khi đổi.
Nhìn trước 2027
Hai xu hướng đang rõ. Thứ nhất, block chuẩn hóa sẽ dần thay shape riêng của từng provider, nên code đa phương thức sẽ ít phụ thuộc SDK hơn. Thứ hai, PDF và audio native sẽ lan sang nhiều model hơn, biến OCR và speech-to-text từ bắt buộc thành tùy chọn. OTel GenAI vẫn ở trạng thái Development, nên đừng xây hệ thống quan sát chỉ dựa trên tên attribute chưa ổn định.
Checklist
- Pin
langchain==1.4.9,langgraph==1.2.20và provider package tương thích; ghi phiên bản trong lockfile. - Đo chi phí ảnh bằng usage thật trên 10 mẫu trước khi cam kết ngân sách.
- Giữ ảnh trong base64 chỉ khi cần; nếu URL công khai, kiểm tra quyền truy cập và thời hạn.
- Viết test cho adapter message: một text + một ảnh, và một message chỉ text.
- Đặt ngưỡng cảnh báo khi request vượt 200K token để tránh surcharge 272K.
