学习笔记 · Obsidian
Chat 模型：云平台与多模态能力
接口基线
Chat model 接受带 role 的消息序列并返回 AIMessage。生产代码不应只读 .content 字符串，还要处理 content blocks、tool_calls、usage、finish reason、refusal/safety 与 provider-specific metadata。流式时则要使用 LangChain 定义的 chunk 合并语义，不自行拼接某一个字段。
主要集成
| 类 / 包 | 认证与初始化 | 文档能力 | 关键限制 |
|---|---|---|---|
ChatAmazonNova / langchain-amazon-nova | Nova API key/base URL；固定 model | tools、structured output、stream/async/usage；图像与视频取决模型，Nova 2 支持视频；有 web grounding 等 system tools | 音频未标支持，无 logprobs；system tool 的外部访问与引用要单独治理 |
ChatAnthropic / langchain-anthropic | Anthropic key；model、timeout/retry 等显式设置 | tools、strict tool use、structured output、细粒度 tool streaming、图像/PDF、prompt caching、content blocks | 能力表无音频/视频/logprobs；文件与图像大小/来源需限制，cache 不能跨授权边界 |
AzureAIOpenAIApiChatModel / langchain-azure-ai | Foundry project endpoint + DefaultAzureCredential | tool/schema、图像、stream/async/usage/logprobs | 无音频/视频标记；模型来自 catalog，能力与配额取决于 deployment |
AzureChatOpenAI / langchain-openai | Azure endpoint + deployment + API version，或 Entra ID token provider | tools/schema、图像、stream/async/usage/logprobs，Responses API/reasoning | Azure OpenAI v1 也可直接用 ChatOpenAI；旧专用类与 v1 路径不应混配，deployment name 不等于基础 model name |
ChatBedrockConverse / langchain-aws | AWS credential chain + region + model access | tool/schema、图像、stream、usage，extended thinking、prompt caching、citations | 能力表不标 native async/logprobs；不同 Bedrock 模型对 Converse、thinking、cache/citation 支持不同 |
ChatAnthropicBedrock / langchain-aws[anthropic] | AWS Bedrock 身份 + Anthropic 扩展 | Anthropic-on-Bedrock 专用语义 | 不与直连 ChatAnthropic 共用默认 endpoint/凭据；地域模型版本必须 pin |
ChatAnthropicVertex / langchain-google-vertexai + anthropic[vertex] | GCP ADC/project/location | Claude on Vertex 的 Chat 访问 | 正文很精简且无能力表；不可用其他 Anthropic/Vertex 页面勾号代替目标模型实测 |
ChatGoogleGenerativeAI / langchain-google-genai | Gemini/Google API key，或 GCP project 触发 Vertex backend；支持 custom endpoint/header/proxy | tools/schema，图像/音频/视频，stream/async/usage；file upload、多模态 content | backend 选择改变身份、地域和数据边界；logprobs 在表中为警示态，不能假设全模型支持 |
ChatVertexAI / langchain-google-vertexai | GCP ADC + project/location | tools/schema、图像/音频/视频、stream/async/usage/logprobs，Google Search/code execution | Chat 索引已标 deprecated；新接入先评估 ChatGoogleGenerativeAI Vertex backend，旧系统迁移需对比 content/tool 契约 |
ChatWatsonx / langchain-ibm | watsonx URL + project/space + API key/token | tools/schema、图像、stream、batch、usage/logprobs | 能力表无音频/视频和 native async；project/space 与 model ID 要配套 |
ChatNVIDIA / langchain-nvidia-ai-endpoints | NVIDIA API Catalog key，或 NIM base_url | tools/schema、图像、stream/async/usage，thinking mode、多模型 URL/base64 | 无音频/视频/logprobs 标记；API Catalog 与自托管 NIM 的 model inventory 、许可和 SLO 不同 |
ChatOCIModelDeployment / langchain-oci + oracle-ads | OCI profile/policies + model deployment endpoint | stream/async/usage/logprobs；tool/schema/多模态均“取决于模型”；有 vLLM 专用类 | 必须对自定义 model server 做全套契约测试；OCI config/profile 不进镜像 |
ChatOCIGenAI / langchain-oci | compartment + service endpoint + OCI principal/profile | tools/schema、图像；Gemini 可 PDF/视频/音频；stream/async/usage | 能力取决于 OCI 托管 provider/model；无 logprobs 标记，并要审查 region/model access |
ChatOpenAI / langchain-openai | OpenAI key；model, timeout, retries, base_url, organization 等 | tools/strict schema/custom tools、Responses API、reasoning、图像/音频、stream/async/usage/logprobs | 无视频标记；仅保证 OpenAI 官方规范。设 custom base URL 时非标准 reasoning 字段可丢失，stream usage 默认值也可变 |
工具调用与结构化输出
bind_tools只把 schema 给模型，真正执行由应用完成。执行前要重新校验类型、租户权限、金额/资源标识与幂等键。- 优先 provider 的 strict/schema 机制，但仍对结果做 Pydantic/JSON Schema 校验。不在 schema 错误后无限“请模型修复”；修复次数纳入 deadline/成本。
- 工具选择、结构化输出和普通自然语言返回三者应定义明确的状态机，不靠检查一段文本是否“像 JSON”来分支。
流式与 usage
- 客户端断开时向 provider 传递 cancel；未取消的请求仍会消耗费用和并发。
- 只有最终 chunk 包含 usage 的 provider 很常见；合并前不宣布计费结果，丢失最终 chunk 时标记 usage unknown。
- 分别监控 time-to-first-token、完整时间、输入/输出 token、cache hit 与 reasoning token，避免把“首字快”误当为完整请求 SLO。
多模态安全
- URL 输入使用 allowlist 或由服务端先下载到受控存储，禁止模型 SDK 访问内网、元数据地址或用户任意 URL。
- 验证 MIME、magic bytes、字节数、页数/分辨率/时长，对文件做恶意内容扫描；base64 也必须在解码前限制长度。
- 同一个模型的 URL、base64、file upload 可能走不同 provider 存储路径，数据保留和删除需分别验证。