学习笔记 · Obsidian
传统 LLM 接口与部署
何时仍应使用 LLM
LLM 类的典型契约是“字符串 → 字符串”。新对话、Agent、工具调用和多模态系统应默认使用 Chat model；传统 LLM 适合旧 completion API、只接受纯 prompt 的自定义端点，或已有大量稳定 PromptTemplate 的兼容系统。
将 Chat 消息手工拼为一段文本会丢失 role、tool call、refusal 和 content block 语义，不能作为长期架构。
集成速查
| 类 / 包 | 主要配置/能力 | 生产注意 |
|---|---|---|
AIMLAPILLM / langchain-aimlapi | API key、model，支持 invoke 与 streaming | 网关背后模型异质；固定路由、错误映射和费用上限 |
AnthropicLLM / langchain-anthropic | Anthropic key + PromptTemplate | 为传统 LLM 表面；新 Claude 对话/tool 功能优先 ChatAnthropic |
AzureOpenAI / langchain-openai | Azure endpoint/deployment/API config；支持 API key 或 Entra ID/credential chain | deployment 名与 model 名不同；固定 API 版本，异步 token provider 与同步凭据不混用 |
BedrockLLM / langchain-aws | Bedrock completion、custom models、guardrails、async callback 示例 | 不同 model provider 的 request/response 不同；guardrail 中断与技术错误分类告警 |
Cohere / langchain-cohere | key、model、invoke | 新对话/Tool 选 ChatCohere；LLM 与 Embeddings/Rerank 配额分开 |
GoogleGenerativeAI / langchain-google-genai | PromptTemplate、streaming、safety settings | safety block 是可预期业务结果，不当 5xx 重试；新多模态对话优先 Chat 类 |
VertexAI / langchain-google-vertexai | GCP project/location，PromptTemplate，safety，Model Garden；页面也混合 ChatVertexAI/多模态例子 | 不要把同页的 Chat/多模态功能归给纯 VertexAI LLM；Model Garden endpoint 要 pin |
HuggingFaceEndpoint / langchain-huggingface | Hub token，serverless/dedicated endpoint，streaming | 专用端点需记录 revision/container，处理 cold start、autoscaling 和 input token limit |
HuggingFacePipeline / langchain-huggingface + transformers | 本地 model/tokenizer/pipeline，GPU、batch GPU、OpenVINO backend | 锁定 revision、tokenizer、dtype/quantization/device；限制 batch/context，监控 OOM 与阻塞 |
WatsonxLLM / langchain-ibm | API key/token + project，invoke/streaming/chaining | 固定 model ID/params；不与 ChatWatsonx 的 tool/AIMessage 契约混用 |
OllamaLLM / langchain-ollama | 本地 model，PromptTemplate，页面有 multimodal 示例 | 本地 model tag/digest、显存、并发和端口访问控制由运维承担 |
OpenAI / langchain-openai | OpenAI key、model、PromptTemplate，可配 HTTP proxy | 传统 completion 不等于 ChatOpenAI；proxy 需身份、TLS 校验和数据边界审查 |
OpenVINO via HuggingFacePipeline / optimum[openvino,nncf] | 转换/加载本地 OpenVINO model，streaming | 转换产物、CPU 指令集、精度/量化和 tokenizer 都必须版本化并做质量回归 |
Pipeshift / langchain-pipeshift | key/model，invoke | 文档契约较精简；上线前补 timeout/retry/stream/usage 检查 |
PredictionGuard / langchain-predictionguard | input processing、PII、prompt injection、output validation、toxicity/factuality | 明确每类防护的 block/warn/fallback；安全层不替代业务授权 |
SagemakerEndpoint / langchain-aws | LLMContentHandler 自定义序列化，支持外部 boto3 session/跨账户 | content handler 是核心契约；请求/响应 MIME、最大 payload、timeout、endpoint variant 与 assume-role 权限要测试 |
初始化模式
生产封装至少显式接受 model/deployment、temperature、max output、stop、connect/read/total timeout、max_retries、streaming 和 callbacks。自托管端点额外需 base URL、TLS/CA、健康检查和 request size 上限。凭据从环境/密钥服务注入，不放进 PromptTemplate、trace tag 或异常消息。
流式、重试与幂等
- completion 生成本身可安全重试的前提是还未向下游提交部分输出；一旦流式吐出内容，自动重放可导致重复文本。
- 对 429/5xx 使用服务端 retry-after + 随机退避，但不超过整体 deadline；对 auth、model not found、schema/content handler 错误不重试。
- 输出需标记 provider/model/revision、finish reason、usage 与是否被 safety/guardrail 中断，不把空字符串一律当成成功。
迁移到 Chat 的方法
- 先把传统 prompt 拆成 system/human 消息，用金丝回放比较输出质量和 token 成本。
- 再将需 JSON 的文本解析改为 structured output，需函数的约定文本改为 tool calling。
- 保留旧 LLM 路径作为可回滚适配器，但不在同一个请求内自动双写外部工具副作用。