企业官网建设流程全解析

Metabase AI 设置详解：AI 供应商接入、模型选择与 Metabot 管理

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase

本文系统讲解 Metabase 管理后台Admin > AI页面的全部配置能力：如何接入 AI 供应商（或启用 Metabase AI service）、为各项 AI 功能指定默认模型与轻量模型、分别配置内部与嵌入式 Metabot，以及用描述、语义类型和术语表提升 Metabot 回答质量。读完本文，你可以独立完成一次生产环境的 AI 配置，并能从源码层面理解这些设置的底层存储与生效机制。

启用 AI 功能

AI 功能在 Metabase Cloud 与自托管 Metabase 上均可用，接入自己的 AI 供应商不要求付费的 Metabase 计划。开启步骤：

1. 进入Admin > AI。
2. 在Connect to an AI provider卡片中点击Add a provider。
3. 选择供应商并填写凭证，参考下文选择 AI 供应商。
4. 点击Connect。
5. 随后配置 Metabot 及页面下方的其他 AI 功能。

从源码看，整个实例的 AI 总开关是设置项ai-features-enabled?，默认值为true（见 src/metabase/llm/settings.clj），它对应页面底部的 “Disable all AI features” 拨动开关（见后文）。

选择 AI 供应商

在Admin > AI页面，你决定 Metabase 可以使用哪些 AI 供应商：

• 自托管 Metabase且想使用 Metabot：需要用自己的凭证 接入一个 AI 供应商。
• Metabase Cloud：可以用自己的凭证接入供应商、使用 Metabase AI service，或两者并用。

注意：在 AI settings 中配置的供应商驱动的是 Metabase内置AI 功能（Metabot、SQL 生成等），而不是 MCP server——MCP server 模式下 AI 由你的客户端提供（参见 MCP 文档）。

Metabase AI service

在 Metabase Cloud 上，可以让 Metabase 公司代为管理 AI。适合两种场景：你没有偏好的 AI 供应商，或希望所有 Metabase AI 成本都通过 Metabase 结算。模型由 Metabase 侧根据内部基准测试选取并持续迭代。使用该服务按 token 用量计费（在 Metabase Cloud 订阅费之外）。

为 Metabot 启用 Metabase AI service 的步骤：

1. 进入Admin > AI。
2. 点击Add a provider，选择Metabase AI service。
3. 同意服务条款。
4. 点击Connect。

移除服务：在供应商列表中点击Metabase AI service旁的...，然后点Remove。该连接用实例的 license token 认证，无需填写 API key，且只能连接一次。在源码中它被标记为 singleton/managed 类型：src/metabase/llm/api/provider.clj 的创建端点会拒绝重复连接；删除该连接还要求超级用户权限，并在 Enterprise 版中取消背后的 Store 订阅（cancel-managed-ai-subscription!）。

接入自己的 AI 供应商

Metabase 支持一批供应商，完整清单、每个供应商需要的凭证字段与可用模型见 支持的 AI 供应商。大多数供应商只需一个 API key，例外包括：Amazon Bedrock 需要 AWS 访问密钥对，Google Gemini Enterprise 需要服务账号密钥文件或 OAuth token。

步骤：

1. 进入Admin > AI。
2. 点击Add a provider。
3. 选择供应商。
4. 填写凭证。表单中的Where do I find this?链接会在新标签页打开对应供应商的密钥管理页面。
5. 点击Connect。

一个便利细节：如果已经复制了 API key，直接把 key 粘贴到供应商网格的任何位置，Metabase 会自动选中匹配的供应商并帮你填好——请核对供应商是否匹配。这个“按前缀识别供应商”的能力来自源码中的供应商类型注册表：每个类型定义了 key 的:prefix（如 Anthropic 的sk-ant-、OpenAI 的sk-、OpenRouter 的sk-or-v1-），见 src/metabase/llm/provider.clj。

连接保存后，其模型会出现在Models卡片中，供你为每个 AI 功能指定模型（见 为每个 AI 功能选择模型）。

值得注意的实现细节：连接不会在凭证被验证通过之前落库。POST /api/llm/providers端点在保存前会调用verify-credentials!，实际向供应商发起一次模型列表请求（对支持探针的类型还会真正执行一次生成来验证工具调用能力），凭证被拒时直接返回 400 并携带供应商的原始错误信息（见 src/metabase/llm/api/provider.clj 与 L441-L448）。因此界面里“连上了”即代表凭证当时可用。

连接多个供应商

可以连接任意数量的供应商。添加第一个之后，卡片标题变为AI providers，按钮变为Add another provider。

同类型可以连接多个，比如两个 Anthropic key 或两个 Azure 部署。通过连接表单中的Advanced settings填写Display name来区分它们，该名称会同时出现在Default model与Mini model下拉框中，于是 “Anthropic” 和 “Anthropic (evals)” 可以并列存在。唯一的例外是 Metabase AI service，只能连接一次。

从源码看，每条连接是一个{:key ... :type ... :name ... :config {...}}结构，存在单一设置项llm-providers的连接列表中；:key是 URL 安全的 slug，缺省等于供应商类型，所以单连接实例的模型引用读起来与旧版一连接一类型时完全一致（见 src/metabase/llm/provider.clj）。

编辑或删除供应商连接

每条连接的...菜单提供：

• Edit：修改显示名、凭证或 API base URL。无需重输 API key——只要不替换，Metabase 会保留已存储的 key。
• Remove：删除连接及其存储凭证。如果Default model来自该连接，Metabase 会自动切换到剩余连接中某个可用的模型；若没有剩余连接，则把 Metabot 报告为未配置。若Mini model选自该连接，则回退为从默认模型推导。

对应后端逻辑在DELETE /api/llm/providers/:key：删除后检查llm-mini-model与llm-metabot-provider是否指向被删连接，指向则清空 mini model 或用fallback-model-ref重新指向第一个可服务模型（见 src/metabase/llm/api/provider.clj）。Metabase AI service 连接只提供Remove，因为它没有自己的凭证可编辑。

连接错误与警告

• 某条连接的凭证失效时，只有该连接报告错误，不影响其他连接（模型列表端点对每条连接独立 try/catch，一条坏连接不会清空其他连接，见 src/metabase/llm/api/provider.clj）。
• 缺少必填字段的连接显示警告图标，在补齐之前 Metabot 无法使用该连接。

用环境变量设置供应商凭证

自托管时，可以改用环境变量代替管理界面配置供应商。这类连接在列表中显示为只读，并附注其来源变量。

环境变量还可以覆盖 UI 管理连接的单个字段。例如只设置MB_LLM_ANTHROPIC_API_BASE_URL时，base URL 取自环境，连接其余部分仍可编辑。源码层面，每个单供应商设置项的 getter/setter 都代理到llm-providers连接列表，环境变量值“阴影化”（shadow）连接中的对应字段——读写都经过连接列表（见 src/metabase/llm/settings.clj 中connection-field-getter/connection-field-setter与llm-anthropic-api-key定义）。

把整个列表交给环境管理，则设置MB_LLM_PROVIDERS为 JSON 连接数组，每个条目含key（URL 安全的 slug）、type、显示name和config凭证 map。此时供应商列表在 UI 中只读，管理方式为修改MB_LLM_PROVIDERS并重启。API 端点对此有硬校验：当检测到llm-providers由环境变量设置时，任何经 API 的增删改都会返回 400（check-connections-not-env-managed!）。

常用环境变量速查（完整列表见 environment-variables.md）：

在 Metabase Cloud 上需要环境变量，请联系支持团队为你的实例设置。

为每个 AI 功能选择模型

Models卡片决定每个 AI 功能运行在哪个模型上。它按连接分组列出各连接可用的模型，条目同时标注连接名与模型名，形如 “Anthropic · Claude Sonnet 4.6”。模型列表来自GET /api/llm/models，服务端对每条连接并发查询，结果带 60 秒 TTL 缓存，且缓存键包含配置哈希与所选模型——凭证一轮换，旧列表立即失效（见 models-cache）。

默认模型（Default model）

Metabot、AI explorations 和 SQL 生成 都运行在Default model上。

嵌入式 Metabot 同样运行在Default model上：Embedded标签页没有单独的模型设置，因此两个 Metabot 使用同一选择。

源码中该选择即llm-metabot-provider设置，值为连接key/模型名字符串，默认anthropic/claude-sonnet-4-6（见 src/metabase/metabot/settings.clj）。模型引用字符串由resolve-model-ref解析为供应商类型、模型与凭证。

轻量模型（Mini model）

快速、高频的轻量任务（例如给对话命名）运行在Mini model上，它应该是比默认模型更便宜、更快的模型。

可以不显式选择 mini model：默认使用与默认模型同一连接中最快的模型（各供应商在注册表中声明了:mini-model，如 Anthropic 的claude-haiku-4-5-20251001、OpenAI 的gpt-5.4-mini，见 src/metabase/llm/provider.clj）。某些供应商没有更小模型时，mini model 回退到默认模型本身。

配置 Metabot

Metabot settings卡片分Internal与Embedded两个标签页，可将内部 Metabase 的 Metabot 与嵌入式 Metabase 上下文分别配置。例如：自己用 Metabase 时开启 Metabot，但不给嵌入式 Metabase 的用户开放 Metabot。每个标签页各有独立的启用开关、verified-content 设置、允许集合与提示词建议。

启用 Metabot

Internal 标签页。

为你的 Metabase 开启或关闭 Metabot。Metabot默认启用。

启用后，Metabot 可帮助用户创建问题、分析数据、解答关于数据的问题；关闭后，Metabot 图标与键盘快捷键被隐藏。要将 Metabot 限定到特定用户/租户组，或限制 token 用量，见 AI controls。

关闭 Metabot 只关闭应用内的 Metabot 功能；如果启用了 MCP server 和 Agent API，它们仍然可用。

源码层面，metabot-enabled?的 getter 是ai-features-enabled?与自身值的逻辑与（见 src/metabase/metabot/settings.clj），因此总开关一开，任何功能开关都被强制关闭；API 入口统一经过check-metabot-enabled!校验（src/metabase/metabot/config.clj）。

启用 Embedded Metabot

Embedded 标签页。

Enable Embedded Metabot开关控制嵌入式 Metabot，同时影响整应用嵌入与模块化嵌入：

• 整应用嵌入：Metabot 图标和键盘快捷键仅在 Metabot 启用时出现；关闭后这些入口一并隐藏。
• 模块化嵌入：该开关不会在任何地方“添加” Metabot——必须显式在应用中包含聊天组件（如 SDK 的MetabotQuestion）。但如果你已经加入了组件，再关闭 Embedded Metabot 开关，组件将停止工作，此时应同时移除或隐藏应用中的组件。

Verified content

Internal 与 Embedded 标签页均可用，独立配置。

Pro 与 Enterprise 版的管理员可以指示 Metabot 只使用经过验证的 models 和 metrics（且只使用 models 与 metrics）。

把 Metabot 限制在已验证的 models/metrics 上有助于产出更可靠的回答——因为你知道 Metabot 能用的数据至少经过人工审核。

自然语言查询使用的集合

Internal 标签页。

选择一个集合（含子集合），限制 Metabot 在 AI exploration 中搜索的范围。点击Pick a different collection更改选择。该设置只影响从+ New > AI exploration发起的对话。

注意两个边界：

• 用户在 AI exploration 中仍可以 @-mention 集合之外的条目；
• Metabot 还能看到使用者当前的上下文（例如正在浏览的 dashboard，即使它不在所选集合中）。

Embedded Metabot 可使用的集合

Embedded 标签页。

把嵌入式 Metabot 指向另一个集合，用于创建查询时搜索 metrics、models 与已保存的问题。点击Pick a different collection选择集合（含子集合）。

选Our analytics等同没有选——想真正收窄范围请选择更小的集合。另外，一旦设置了集合，tables 会从嵌入式 Metabot 的搜索结果中消失，因此要选一个包含你希望人们基于其构建内容的 metrics 与 models 的集合。

这个设置只收窄搜索范围，不是权限替代品：嵌入式 Metabot 仍能读取和查询使用者有权限的任何内容，也能看到该用户最近浏览的条目（无论其属于哪个集合）。将 Metabot 限制到 verified content 可以把这些近期条目进一步收窄到 verified、official 与 Library 内容，但仍不限制在你所选集合内。要控制嵌入中人们能触达的数据，请设置数据权限。另见 Set up AI chat in Metabase。

提示词建议（Prompt suggestions）

Internal 与 Embedded 标签页均可用，独立配置。

用户打开新的 Metabot 对话时，Metabase 会基于实例中热门的 models 与 metrics 展示若干建议提示词。

点击Regenerate suggested prompts重新生成一组。也可以逐条运行提示词以测试 Metabot 的回答，或删除无用的提示词。Internal 与 Embedded 各自维护独立的一组建议，在一个标签页重新生成不影响另一个。后端实现是删除旧提示后重新生成（见 src/metabase/metabot/api/metabot.clj 中delete-all-metabot-prompts与generate-sample-prompts的组合调用）。

禁用全部 AI 功能

AI 功能页面底部的Disable all AI features是一个总闸。打开后，无论上面各功能开关状态如何，整个实例的所有 AI 功能都会被隐藏——Metabot、行内 SQL 生成、MCP server、Agent API 以及所有嵌入式聊天组件。

它适用于“全实例关停而不用断开供应商、也不必逐个改功能开关”的场景；再次关闭即恢复原有配置。对应设置项ai-features-enabled?（默认true，见 src/metabase/llm/settings.clj），如前所述，metabot-enabled?与embedded-metabot-enabled?的 getter 都以它为前置条件。

需要更细粒度的控制，见 AI usage controls。

让 Metabot 发挥最大价值的技巧

提升 Metabot 表现最核心的做法，是把数据整理得像为新（人类）同事入职做准备一样。具体是：

• 为数据与内容添加描述
• 确保每个字段的语义类型正确
• 在术语表中定义领域术语

为数据与内容添加描述

为 models、metrics、dashboards 和 questions 添加描述。描述应提供上下文、定义术语、解释业务逻辑。管理员还可以整理 table 元数据，为表及其字段添加描述。

例如，一个提供额外上下文的好描述：

This is a unique ID for the product. It is also called the "Invoice number" or "Confirmation number" in customer facing emails and screens.

你也可以让 Metabot 帮你写描述。但 Metabot 只能访问数据库里的数据，它不可能知道“这个 ID 在 Web 应用里叫 Invoice number”这类值得记录的业务上下文。

确保每个字段的语义类型正确

确保每个字段的语义类型准确反映其“含义”。例如created_at这类字段应使用 Creation date 语义类型。

Metabase 会尝试自动设置语义类型，但应逐字段确认其相关语义类型，参见 Data types and semantic types。也可以为 models 设置语义类型。

在术语表中定义领域术语

把组织内的术语、缩写与业务专有名词加入术语表（glossary）。提交提示词时，Metabot 可以查术语表来更好地理解请求。

例如，在术语表中把 “MRR” 定义为 “Monthly Recurring Revenue”，那么当有人问 “What's our MRR for Q4?” 时 Metabot 就知道你在说什么。这对行业黑话、内部产品名或组织专属缩写尤其有用。

Metabot 的权限就是 Metabase 的权限

Metabot 继承与其对话的用户的权限，因此无需为 Metabot 单独设置权限。任何人使用 Metabot 时，Metabot 只能看到该用户有权限看到与执行的内容。

也就是说，要限制每个人眼中 Metabot 能看到的数据，只需像往常一样对其组应用数据与集合权限即可，这些权限同样适用于该用户通过 Metabot 的一切操作。

查看 Metabot 用量

• 使用Metabase AI service时，可前往Admin > AI查看本月 Metabot 请求数。若未登录 Metabase Store，需先登录商店，再回到 Metabase 的 license 页面查看用量。
• 使用自己的供应商凭证时，用量与成本可在该供应商的仪表盘跟踪。
• Pro/Enterprise 版还可使用详细的 AI usage auditing，按用户、工具、功能等维度查看 AI 用量明细。

延伸阅读

• 使用 Metabot
• 支持的 AI 供应商
• MCP server
• AI 隐私
• AI 访问与用量控制
• AI 用量审计
• Metabot 定制
• Metabot 系统提示词

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase