学习笔记 · Obsidian
Legacy LLM：文本补全与迁移
结论
这一 family 是 string-in/string-out 的 completion wrapper。官方总览和多个组件页都提示：新模型通常应使用 chat integration。组件页没有统一的 tool calling、structured output 或 streaming feature matrix，因此不能把 Chat 同名 provider 的能力外推到 LLM 类。
保留 LLM 路径的合理场景只有：
- 既有 prompt 已绑定特定 completion/instruct 模型；
- 需要模型原生前缀补全语义；
- 已完成回归和成本验证，迁移收益暂时不足。
组件矩阵
| 类 / 包 | 认证与示例模型 | Local / Serializable | 文档状态与迁移方向 |
|---|---|---|---|
AzureOpenAI / @langchain/openai | Azure deployment/API version；key 或 Managed Identity；gpt-3.5-turbo-instruct | ❌ / ✅ | 文档明确建议多数场景改 AzureChatOpenAI；旧 Azure SDK 已弃用 |
CloudflareWorkersAI / @langchain/cloudflare | account id + token；Workers AI model | ❌ / ✅ | completion wrapper；可用 AI Gateway base URL |
Cohere / @langchain/cohere | COHERE_API_KEY；command | ❌ / ✅ | Cohere generate endpoint 已弃用；迁移 ChatCohere |
Fireworks / @langchain/fireworks | FIREWORKS_API_KEY + exact model ID | ❌ / ✅ | 维护 completion 时固定托管模型；新 instruct/chat 先评估 ChatFireworks |
VertexAI / @langchain/google-vertexai | ADC/web credential；gemini-pro 示例 | ❌ / ✅ | 旧 Google Vertex 包；Node 与 Web/Edge 路径不同 |
WatsonxLLM / @langchain/ibm | IAM/bearer/CP4D；model/deployment/gateway | ❌ / ✅ | 提供 chaining、参数覆写和 tokenization；迁移时保留 provider 参数语义 |
JigsawStackPromptEngine / @langchain/jigsawstack | JIGSAWSTACK_API_KEY | 文档未给标准表 | prompt engine 专用 wrapper，不等同普通 foundation model |
MistralAI / @langchain/mistralai | MISTRAL_API_KEY；codestral-latest | ❌ / ✅ | 支持 HTTP hooks；Chat 场景迁移 ChatMistralAI |
Ollama / @langchain/ollama | 本地 daemon；llama3 / llava | ✅ / ❌ | 文档建议多数场景改 ChatOllama；LLM 路径另有 LLaVA base64 image 示例 |
OpenAI / @langchain/openai | OPENAI_API_KEY；gpt-3.5-turbo-instruct | ❌ / ✅ | 页面明确只在特定 instruct 模型下考虑；其他场景用 ChatOpenAI |
TogetherAI / @langchain/together-ai | TOGETHER_AI_API_KEY + model | ❌ / ✅ | 页面称 legacy completions class；chat/instruct 优先 ChatTogetherAI |
YandexGPT / @langchain/yandex/llms | YC_IAM_TOKEN 或 YC_API_KEY | 文档未给标准表 | service account 需语言模型角色；旧格式页面 |
初始化与运行时差异
典型 LLM 仍通过 new Xxx({ model, temperature, maxTokens, timeout, maxRetries }) 后 invoke(string)。但 provider 配置不可强行统一：
- Azure 绑定 instance、deployment 与 API version，非默认域还需 base path；Managed Identity 使用 token provider。
- Cloudflare 示例以 account id/token 调 Workers AI；示例读取环境变量用了 Deno 形式，目标 runtime 必须自行适配安全配置。
- Vertex Node 包使用 Google auth；browser/Edge 应换 web package，不能把服务账号私钥打进前端。
- IBM 的 model、deployment、project/space 与 gateway alias 是不同调用模式。
- Ollama 由本地进程、模型文件与硬件决定可用性，不存在第三方 SLA。
Multimodal 的例外不改变默认决策
Ollama LLM 页展示 LLaVA 通过 .bind({ images: [base64] }) 输入图片。这证明该特定 wrapper/model 路径存在多模态能力，但不代表 legacy LLM family 普遍支持多模态，也不提供标准 content blocks、tool calls 或 structured output 契约。新多模态系统仍优先 Chat Model。
从 LLM 迁到 Chat 的步骤
- 固定现有 package、model、prompt、stop、temperature、max tokens 与输出 parser，建立 golden set。
- 选择同 provider 的 Chat 类，把原字符串拆成 system/user messages；不要简单把完整 prompt 放进一条 user message后就宣称等价。
- 比较输出质量、拒答、token usage、延迟、stream chunk、stop reason 和错误类型。
- 对 parser 改用 structured output 时，保留 schema validation 与 fallback；不要把迁移同时扩大为 agent/tool 重构。
- 灰度双跑，只让旧路径产生用户响应；记录差异但脱敏 prompt/response。
- 新路径达标后按配置切流，保留旧模型和 package lockfile 作为短期回滚。
生产风险
- completion 模型和 endpoint 更容易被 provider 下线；必须监控 deprecation 与 404/410，而不是只重试。
- 字符串 prompt 容易把 system instruction、用户输入和检索内容拼接在同一信任级；迁移前也要做模板转义与边界标记。
- 没有标准 feature table 就不对 tool、JSON、usage 或 streaming 做默认承诺；每项能力单独 contract test。
- custom base URL 必须固定受信 host，并验证 TLS、代理 header、超时和 streaming compatibility。
- hooks 和日志只能记录 metadata；prompt、completion、credential 与私有文档不进入普通日志。
选型门禁
新增代码若选择本页任一 LLM 类，应在设计记录中说明为何 Chat Model 不适用、目标 completion endpoint 的支持周期、迁移/回滚路径和真实 API 验证结果。否则默认回到 Chat Model。