OneUptime LLM 提供商配置实战：从数据模型到集群内 vLLM 的完整落地指南-平芜编程栈

OneUptime LLM 提供商配置实战：从数据模型到集群内 vLLM 的完整落地指南

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

本文基于 OneUptime 官方文档《LLM-Anbieter》(LLM 提供商指南)，系统讲解如何在 OneUptime 中接入、配置和排障各类 LLM 提供商：覆盖 7 种提供商类型的选型表、逐字段的数据模型、项目级与全局提供商的解析规则，以及通过 Helm 在 Kubernetes 集群内部署 vLLM 本地推理服务的完整流程。读完本文，你可以独立完成任意提供商的接入，并理解 OneUptime 底层请求重试、参数自适应与安全出网控制等实现机制。

LLM 提供商支撑哪些 AI 功能

OneUptime 允许接入多家大模型提供商，为平台内的 AI 功能提供推理能力。根据官方文档，接入提供商后你可以获得以下自动化能力：

事件笔记（Incident Notes）：自动生成详细的事件笔记与更新；
通知笔记：为通知生成有意义的描述与上下文；
计划维护笔记：自动为维护事件生成说明；
事件复盘报告（Postmortem）：自动起草完整的事件复盘报告；
代码改进建议：当你的代码仓库接入 OneUptime 后，平台会使用你配置的提供商分析遥测数据（日志、追踪、指标、异常）并提出代码改进建议。

对于OneUptime SaaS（云托管版）用户，平台默认提供一个已配置好的全局 LLM 提供商，无需任何额外配置即可使用全部 AI 功能；如果你希望使用自己的 API 密钥或指定提供商，仍可按本文流程创建自定义提供商。

LlmProvider 数据模型：每个配置项意味着什么

提供商配置在 OneUptime 中是一个完整的数据库实体，定义见 LlmProvider 模型。理解每个字段的约束，是正确填写表单的前提：

字段	类型/约束	说明
`name`	必填，Name	该 LLM 配置的友好名称（如 "Production OpenAI"、"Local Ollama"）
`description`	可选，LongText	用于区分该提供商用途的描述
`slug`	必填，由`name`自动生成	全局唯一标识
`llmType`	必填	提供商类型：OpenAI、AzureOpenAI、Anthropic、Groq、Mistral、Ollama、OpenAICompatible
`apiKey`	可选，加密存储	对 OpenAI、Azure OpenAI、Anthropic、Groq、Mistral 必填；Ollama 与 OpenAI Compatible 可选。从列级访问控制看，读取该字段仅限 Project Owner 与 ProjectAdmin（其余角色仅能写）
`modelName`	可选	要使用的模型名，如`gpt-4o`、`claude-3-opus-20240229`、`llama2`
`baseUrl`	可选，ShortURL	Azure OpenAI、Ollama、OpenAI Compatible 必填，其他提供商可选
`additionalParams`	可选，JSON	额外透传给提供商 API 的参数对象，最后合并、覆盖默认值（例如为推理模型指定`max_completion_tokens`）
`projectId`	可选	归属项目；为 null 时是全局提供商（`isGlobalLlm = true`时对所有项目可见）
`isDefault`	默认 false	是否为项目默认提供商；设为 true 后全局提供商将不被该项目使用
`costPerMillionTokensInUSDCents`	默认 0	每百万 token 成本（美分），用于全局提供商的计费场景

其中llmType的取值由 LlmType 枚举固定为 7 种；OpenAICompatible在源码注释中明确覆盖 vLLM、LocalAI、LM Studio、text-gen-webui 等“说 OpenAI/chat/completions协议、通常自托管在自定义 Base URL 且常常无需密钥”的服务。

支持哪些提供商：选型速查表

提供商	说明	API 密钥	Base URL
OpenAI	GPT-4、GPT-4o、GPT-3.5 Turbo 等	必填	否（使用默认）
Azure OpenAI	部署在你自己 Azure 环境中的 OpenAI 模型	必填	必填
Anthropic	Claude 3 Opus / Sonnet / Haiku 等	必填	否（使用默认）
Groq	Llama、Mixtral 等开放模型的高快推理	必填	否（使用默认）
Mistral	Mistral 托管模型	必填	否（使用默认）
Ollama	自托管开源模型（Llama 2、Mistral、CodeLlama 等）	否	必填
OpenAI Compatible	任何 OpenAI 兼容服务器（vLLM、LocalAI、LM Studio 等）	否（可选）	必填

创建提供商：标准操作步骤

步骤 1：进入提供商设置

登录 OneUptime 仪表盘；
进入AI Agents（AI 代理） > LLM Providers（LLM 提供商）；
点击Create LLM Provider（创建 LLM 提供商）。

步骤 2：填写配置字段

Name：便于理解的名字（如 "Production OpenAI"、"Local Ollama"）；
Description（可选）：说明该提供商的用途；
LLM Type：OpenAI、Azure OpenAI、Anthropic、Groq、Mistral、Ollama 或 OpenAI Compatible；
API Key：对 OpenAI/Azure OpenAI/Anthropic/Groq/Mistral 必填，对 Ollama 与 OpenAI 兼容服务器可选；
Model Name：具体模型名（如gpt-4o、claude-3-opus-20240229、llama2）；
Base URL（可选）：自定义 API 端点 URL。Azure OpenAI、Ollama、OpenAI Compatible 必填，其余可选。

保存后，可以使用提供商条目上的Test（测试）按钮验证连接、模型名与 Base URL 是否正确——前端测试逻辑实现在 TestLLMProvider 工具。

默认值的两个隐藏行为（来自服务端 Hook）

LlmProviderService 在创建与更新时注入了两条默认规则，表单上不会直接提示，但直接影响行为：

新建即默认：onBeforeCreate中若未显式指定isDefault，新提供商会被自动设为项目默认（isDefault = true）；
默认互斥：当某提供商被设为isDefault时，同项目内其他提供商的isDefault会被自动置为 false（创建与更新两条路径均保证项目内至多一个默认）。

分提供商配置示例

OpenAI

从 OpenAI 平台获取 API 密钥；
LLM Type 选择OpenAI；
填入 API 密钥；
选择模型名，常见取值：
- gpt-4o— 能力最强，适合复杂任务；
- gpt-4o-mini— 更快、成本更低；
- gpt-4-turbo— 性能与速度均衡；
- gpt-3.5-turbo— 快速且经济。

Name: Production OpenAI LLM Type: OpenAI API Key: sk-xxxxxxxxxxxxxxxxxxxx Model Name: gpt-4o

Anthropic

从 Anthropic Console 获取 API 密钥；
LLM Type 选择Anthropic；
填入 API 密钥；
常见模型取值：
- claude-3-opus-20240229— 能力最强；
- claude-3-sonnet-20240229— 智能与速度均衡；
- claude-3-haiku-20240307— 最快、最紧凑；
- claude-3-5-sonnet-20241022— 更新的 Sonnet 模型。

Name: Production Anthropic LLM Type: Anthropic API Key: sk-ant-xxxxxxxxxxxxxxxxxxxx Model Name: claude-3-5-sonnet-20241022

Ollama（自托管）

Ollama 允许你在本地或自己的基础设施上运行开源 LLM：

安装 Ollama（ollama.ai）；
下载模型：ollama pull llama2；
确认 Ollama 已启动且可从 OneUptime 服务器访问；
LLM Type 选择Ollama；
填写 Base URL（如http://localhost:11434）；
填写已下载的模型名。

Name: Local Ollama LLM Type: Ollama Base URL: http://localhost:11434 Model Name: llama2

常用 Ollama 模型：llama2（Meta Llama 2）、llama3（Meta Llama 3）、mistral（Mistral AI）、codellama（代码向 Llama）、mixtral（Mixture-of-Experts）。

OpenAI Compatible（vLLM、LocalAI、LM Studio 等）

任何实现了 OpenAI/chat/completions协议但不是 OpenAI 本身的服务器都走这个类型：

启动你的 OpenAI 兼容服务器，记下 Base URL（通常以/v1结尾）；
LLM Type 选择OpenAI Compatible；
填写Base URL（必填），如http://your-server:8000/v1；
填写Model Name（必填）——必须与服务器提供的模型完全一致；
API Key仅在服务器要求鉴权时填写，无密钥服务器留空。

无密钥 vLLM 示例：

Name: Self-Hosted vLLM LLM Type: OpenAI Compatible Base URL: http://vllm.internal:8000/v1 Model Name: meta-llama/Llama-3.1-8B-Instruct API Key: （留空）

提示：保存后务必用提供商条目上的Test按钮验证连接、模型名与 Base URL。

Base URL 的容错处理：LLMService 中buildOpenAICompatibleChatCompletionsUrl会把各种填写习惯归一化到正确端点——已经是完整端点（.../chat/completions）则原样使用；带路径（.../v1）则追加/chat/completions；只填了服务器根地址（http://host:8000）则自动补上/v1/chat/completions（vLLM、LocalAI 等默认在/v1下暴露 API，漏填/v1是最常见错误，会得到{"detail":"Not Found"}）。该逻辑还处理了 query/fragment 剥离与尾部斜杠清理，避免拼出.../v1//chat/completions。

提供商解析规则：项目默认、全局与“项目自有”

AI 功能实际使用哪个提供商，由 LlmProviderService 的一组方法决定，理解它们可以解释很多“配置了却不生效”的现象：

getLLMProviderForProject（通用解析）：先查项目的isDefault = true提供商；查不到再回退到projectId = null && isGlobalLlm = true的全局提供商。这印证了文档中“SaaS 全局提供商开箱即用、自定义提供商一旦设为项目默认即接管”的描述；
getProjectOwnedLlmProvider（项目自有解析）：只认项目自己的提供商（先默认、否则按创建时间取第一个），永远不回退到全局——项目级 AI Agent 等场景走的就是这条规则，这也是“项目级 AI Agent 不能使用全局提供商、必须配置项目级提供商”这一产品规则的实现来源（对应测试见 LlmProviderProjectOwned.test.ts）;
getLlmProviderForMeteredAgentPath（计量 Agent 路径）：服务端中介的/ai-agent-data/llm-completion端点走AIService.executeWithLogging，调用会记入LlmLog，使用全局提供商时按 token 计量计费，并受每日自主 token 预算约束。此路径上项目自有提供商优先，无自有提供商时云版本也会回落到全局提供商；
isProviderUsableByProject（可用性谓词）：所有接受调用方指定llmProviderId的入口统一经过该判断——全局提供商对所有人可用，项目自有提供商仅对本项目可用；ID 不存在、不属于本项目或不是合法 UUID 时返回 false 而不是抛错，避免 Postgres 类型转换异常。

此外getProviderForChat支持在聊天中显式指定提供商，若指定的提供商已删除或无权使用，则自动回退到默认解析，保证会话不会因提供商“消失”而中断。

集群内部署 vLLM（Helm 方式）

如果你用 Helm 部署 OneUptime 自托管版，可以在集群内运行 vLLM 这类 OpenAI 兼容推理服务器，让数据完全不出自己的基础设施。相关配置集中在 values.yaml 的 vllm 段，Kubernetes 清单模板见 vllm.yaml。

最小启用配置（需要 NVIDIA GPU 节点）：

vllm: enabled: true model: Qwen/Qwen2.5-1.5B-Instruct

默认值要点（摘自 values.yaml 注释）：

enabled: false默认关闭，启用需节点安装 NVIDIA device plugin 或 GPU Operator；
image.tag: v0.24.0固定 vLLM 版本，镜像 10GB+，节点首次拉取较慢；
model默认Qwen/Qwen2.5-1.5B-Instruct——Apache-2.0 许可且非 gated（无需 HuggingFace token）；
servedModelName为空时，OneUptime 表单里的 Model Name 必须填完整的 HuggingFace 模型 ID；
toolCalling.enabled: true默认开启，并注入--enable-auto-tool-choice --tool-call-parser=hermes（hermes适配默认 Qwen2.5 模型家族）。这一点至关重要：OneUptime 的 AI Copilot 与 AI Agent 都依赖 OpenAI 风格 tool call，未开启时所有请求会返回 400（"auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set）；更换模型家族时需同步更换 parser（如 Llama 用llama3_json/pythonic，Mistral 用mistral）；
persistence: { enabled: true, size: 50Gi }为模型权重与编译缓存提供持久卷（每副本一个 PVC），注意volumeClaimTemplates不可变，改 size/storageClass 需按文档重建 StatefulSet；
resources.limits默认请求 1 块nvidia.com/gpu——无 GPU 节点时 Pod 会保持 Pending 而非 crash-loop，这是刻意的清晰信号；
vllm.globalProvider.enabled默认true：启动时自动把该 vLLM 注册为全局 LLM 提供商（默认名 "OneUptime AI"），所有项目的 AI 功能无需手工配置即可工作；该提供商由环境变量声明式管理，关闭vllm.enabled或globalProvider.enabled会在下次部署时移除自动注册的条目，且手动修改其受管字段（名称、描述、类型、模型、Base URL、密钥）会被覆盖。

部署与验证步骤：

在 Helm values 中启用vllm并指定model；
执行helm upgrade，等待 vLLM Pod Ready（首次启动会下载模型）；
若自动注册生效（默认），全局 AI 功能即刻可用；
注意产品规则：项目级 AI Agent 不能使用全局提供商，仍需为项目单独创建一个指向该 vLLM 的项目级提供商。

关闭自动注册时的手工配置（vllm.globalProvider.enabled: false）：

LLM Type 选择OpenAI Compatible（vLLM 讲 OpenAI 协议）；
Base URL 填集群内部地址：http://<release>-vllm.<namespace>.svc.cluster.local:8000/v1；
Model Name 填完整 HuggingFace 模型 ID（或vllm.servedModelName，若已设置）；
仅在设置了vllm.apiKey时填写 API Key，无密钥部署留空。

Name: In-Cluster vLLM LLM Type: OpenAI Compatible Base URL: http://oneuptime-vllm.default.svc.cluster.local:8000/v1 Model Name: Qwen/Qwen2.5-1.5B-Instruct API Key: （未设置 vllm.apiKey 时留空）

GPU 调度、gated 模型（需vllm.huggingFace.token）与调优选项（--max-model-len、--gpu-memory-utilization、--tensor-parallel-size等，通过vllm.extraArgs注入）详见 Helm Chart 的 README 与 values.yaml 内注释。

调用链路原理：重试、参数自适应与出网防护

配置保存后，实际请求由 LLMService 发出。几项工程细节解释了为什么自托管与商用端点行为会有差异：

按类型分发：getCompletion把 OpenAI、Groq、Mistral、OpenAICompatible 统一走 OpenAI 兼容线协议，Azure OpenAI、Anthropic、Ollama 各自独立实现；
重试策略：每次调用默认最多 10 次尝试（DEFAULT_REQUEST_ATTEMPTS = 10），指数退避且上限 8 秒，整体重试预算默认 5 分钟，且只对“重试有意义”的瞬时错误（429、连接拒绝、502 等）消耗重试——密钥错误、模型不存在这类每次必败的错误不会浪费重试梯；
错误驱动的请求自适应：不同模型家族对生成参数要求不同（如推理模型拒绝max_tokens只认max_completion_tokens；旧模型相反）。服务采用“让提供商报错→按错误修正参数→重发”的策略，并把每个端点实际接受的参数组合缓存在进程内（TTL 1 小时、上限 500 条），因此只有每个提供商的首次完成会付出探测成本；
出网防护（Egress Guard）：由于baseUrl对普通项目成员可写而apiKey仅 Owner/Admin 可读，未加防护的请求可能让成员把端点改指到可控主机、从鉴权头收集解密密钥。buildGuardedRequestOptions通过DataSourceEgressGuard在验证时即把目标地址固定到 socket 并拒绝重定向；自托管场景下内网地址保持可达（自托管 Ollama 部署在 10.x 是文档化场景），相关行为由 LLMServiceEgressGuard.test.ts 等测试覆盖；
additionalParams的 fail-closed 白名单：对受保护的无人值守完成，提供商配置的额外参数只允许保留纯生成类字段（temperature、top_p、stop、response_format、max_completion_tokens等），tools、stream等能力字段被拒绝，防止配置侧悄悄放大请求能力；Ollama 线协议对model、messages、tools、stream四个保留键同样不可被覆盖。

Base URL 归一化、模型兼容性、重试策略等都有对应测试：LLMServiceBaseUrl.test.ts、LLMServiceModelCompatibility.test.ts、LLMServiceRetryPolicy.test.ts。

自定义 Base URL 的适用场景

企业部署或经由代理访问时，可以指定自定义 Base URL：

Azure OpenAI：使用你的 Azure 端点 URL；
OpenAI 兼容 API：任何遵循 OpenAI API 规范的接口；
私有 Ollama 实例：内网 Ollama 服务器地址。

最佳实践

使用描述性名称：如 "Production GPT-4"、"Development Ollama"，便于在聊天切换器（getSelectableProvidersForProject同时列出项目提供商与全局提供商）中识别；
保护 API 密钥：密钥加密存储且读取权限仅限 Owner/Admin，但仍不要分享；
配置后立即测试：用提供商条目的 Test 按钮确认连接、模型名与 Base URL 正确；
监控用量：关注 API 用量以控制成本；使用全局提供商计费时，costPerMillionTokensInUSDCents字段决定了每百万 token 的计价。

故障排查

连接问题

OpenAI / Anthropic：确认 API 密钥有效且有额度；
Ollama：确认 Ollama 服务已启动、Base URL 正确；
OpenAI Compatible：确认 Base URL 以/v1结尾（或与你服务器实际路径一致）、模型名与服务器提供的模型完全匹配、且仅在服务器要求时填写 API 密钥；
防火墙：确认网络放行到提供商 API 的出向连接。

模型未找到