Baserow AI 助手Kuma部署指南从 pydantic-ai 模型配置到知识库检索【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow本文围绕 Baserow 仓库中的 docs/installation/ai-assistant.md 展开讲解如何在自托管的 Baserow 实例中启用基于 pydantic-ai 的 AI 助手Kuma配置数据库化的 AI Provider 或遗留环境变量回退、接入多家 LLM 提供商、可选地部署 embeddings 服务开启知识库检索并在助手不出现或不可用时定位问题。读完本文你可以独立完成从最小启用、提供商预置、到模型解析链路排障的完整 DevOps 流程并理解resolve_assistant_model在源码层面的解析顺序。1. 核心概念pydantic-ai 与模型选择的三层优先级Baserow 的 AI 助手构建在 pydantic-ai数据库优先当ai-providers特性启用时实例管理员在Admin AI providers AI features中配置提供商并选定 Kuma 模型。工作区可以继承该选择、改用对 Kuma 可用的其他模型或在工作区 AI 提供商设置中禁用 Kuma。遗留环境变量回退BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL在ai-providers特性未启用或其数据库选择处于“未配置/无效”状态时继续生效但特性启用后一次显式禁用explicit disable优先级最高不会回落到遗留变量。显式模型参数调用方可通过参数直接指定模型绕过持久化选择源码中以sourceexplicit标记。从resolve_assistant_model()的实现看解析顺序为显式参数 → 数据库中的 Kuma 设置状态为unconfigured/invalid时回退 legacydisabled时直接抛出AssistantModelDisabledError→ 遗留环境变量。官方文档同时指出助手主要在gpt-oss-120b系列模型上做过测试其他模型也可以使用。模型解析结果会冻结为不可变的ResolvedAssistantModelProfile并在一次逻辑请求内复用避免请求中途模型选择被改动。2. 最小启用数据库化 Provider 与遗留回退2.1 全新安装推荐路径对于新的数据库化部署启用ai-providers特性后在管理界面添加提供商及其模型。在每个模型上选择它对哪些功能可用——Kuma、AI Fields、AI Agent actions 或任意组合——然后在AI features区域选定 Kuma 模型。可用性只是允许某功能选用该模型并不强制 AI Fields 或 AI Agent actions 使用 Kuma 的模型。使用Test model可逐一验证所选功能AI Fields 与 AI Agent actions 检查文本响应Kuma 额外检查 tool calling对应源码中的test_model_text_and_tool_calling探测。对于已有安装升级与导入步骤见 docs/development/feature-flags.md。要点Schema 迁移在常规升级时执行只有在采纳数据库化配置时才需要执行 provider 导入与重新发布仅关闭特性升级不需要带显式 provider 覆盖的集成保留自身连接配置导入前需核对模型列表、部分覆盖与可选端点重新发布站点或 workflow 前检查待处理的草稿变更因为它们会随发布一起生效。2.2migrate_ai_provider_settings命令的行为边界migrate_ai_provider_settings命令只导入遗留 AI provider 配置它不导入BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL也不导入 Kuma 使用的 provider 原生凭据。因此在导入后助手会停留在遗留回退模式直到管理员完成三步在数据库中配置同一提供商连接 → 将某个模型标记并测试通过 Kuma → 显式选中它。由于数据库选择是权威的切换前务必核对其凭据与端点。要回滚该选择在实例 AI feature 设置中选择Use legacy environment model该选项会同时显示当前配置模型。注意该选项的渲染位置是web-frontend 进程只有当BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL或已废弃的UDSPY_LM_MODEL有值且对 web-frontend 进程可见时选项才可点。只在后端设置变量会导致选项保持禁用而后端回退仍能解析——web-frontend/env-remap.mjs 中可以看到前端确实会把BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL或UDSPY_LM_MODEL重映射为NUXT_PUBLIC_BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL。选择Disabled则是有意关闭 Kuma。因此使用遗留回退且采用 Docker Compose 或多服务架构时必须把BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL同时配置在 backend 与 frontend 两个服务中。仓库的 docker-compose.yml 中该变量就分别出现在 backend 与 web-frontend 两个服务段内约 L294 与 L406。2.3 最小环境变量仅遗留回退需要# Required only for the legacy fallback BASEROW_ENTERPRISE_ASSISTANT_LLM_MODELopenai:gpt-5.2 OPENAI_API_KEYyour_api_key # Optional - adjust LLM temperature (default: 0.3) BASEROW_ENTERPRISE_ASSISTANT_LLM_TEMPERATURE0.3关于 temperature控制主助手 LLM 响应的随机性默认 0.3聚焦、一致的响应更高等值视模型而定 更有创造力/多变的响应更低等值如 0–0.1 更分析型。注意即使 temperature 为 0.0结果也不会完全确定。源码层面BASEROW_ENTERPRISE_ASSISTANT_LLM_TEMPERATURE在 settings.py 中被解析为float或None并仅在ORCHESTRATOR角色生效见 model_profiles.py。从源码结构看助手内部按角色细分了模型配置ORCHESTRATORtemperature 0.3、timeout 30s、SUBAGENT0.3/20s、UTILITY0.1/20s、SAMPLE0.5/20s、TITLE0.7/15s、SUGGESTIONS0.6/30s环境变量只覆盖编排器的 temperature其余角色保持内置默认值。3. 遗留回退的 Provider 预置选择其中一个provider 代码块并设置其变量。pydantic-ai 对每个提供商使用标准环境变量如OPENAI_API_KEY、GROQ_API_KEY并按模型前缀自动检测 provider 与路由。OpenAI / OpenAI 兼容端点BASEROW_ENTERPRISE_ASSISTANT_LLM_MODELopenai:gpt-5.2 OPENAI_API_KEYyour_api_key # Optional: point to an alternative OpenAI-compatible endpoint OPENAI_BASE_URLhttps://eu.api.openai.com/v1 # or OPENAI_BASE_URLhttps://your-resource-name.openai.azure.comAnthropicBASEROW_ENTERPRISE_ASSISTANT_LLM_MODELanthropic:claude-sonnet-4-20250514 ANTHROPIC_API_KEYyour_api_keyAWS Bedrockpydantic-ai 支持两种 Bedrock 认证方式任选其一。方式 A — 标准 AWS 凭据boto3BASEROW_ENTERPRISE_ASSISTANT_LLM_MODELbedrock:openai.gpt-oss-120b-1:0 AWS_ACCESS_KEY_IDyour_access_key AWS_SECRET_ACCESS_KEYyour_secret_key AWS_DEFAULT_REGIONeu-central-1任何 boto3 兼容的凭据方式均可环境变量、IAM 角色、实例配置、~/.aws/credentials等。方式 B — Bedrock Bearer TokenBASEROW_ENTERPRISE_ASSISTANT_LLM_MODELbedrock:openai.gpt-oss-120b-1:0 AWS_BEARER_TOKEN_BEDROCKyour_bearer_token AWS_DEFAULT_REGIONeu-central-1GroqBASEROW_ENTERPRISE_ASSISTANT_LLM_MODELgroq:openai/gpt-oss-120b GROQ_API_KEYyour_api_keyGoogleGeminiBASEROW_ENTERPRISE_ASSISTANT_LLM_MODELgoogle:gemini-3.6-flash GOOGLE_API_KEYyour_api_key在 Google AI Studio 创建密钥。使用 Vertex AI 时改用google-cloud前缀此时GOOGLE_API_KEY被视为 Vertex AI Express Mode 密钥基于项目的访问则使用 Application Default Credentials。源码中 model_profiles.py 对google/google-gla/google-cloud/google-vertex前缀还会执行sanitize_google_model_settings对模型设置做适配_normalize_model_string会把google-gla、google-vertex等别名映射为 pydantic-ai 可识别的 provider。OllamaBASEROW_ENTERPRISE_ASSISTANT_LLM_MODELollama:gpt-oss:120b # Point to your Ollama instance (defaults to http://localhost:11434/v1) OLLAMA_BASE_URLhttp://localhost:11434/v1pydantic-ai 会自动根据模型前缀检测 provider 并路由请求。4. 知识库检索embeddings 服务如果部署方式没有自动配置 embeddings需要单独运行 Baserow embeddings 服务并让 Baserow 指向它。开发者使用 Docker Compose 时可直接给COMPOSE_PROFILES加上ai如COMPOSE_PROFILESai或COMPOSE_PROFILESai,optional详细步骤见 docs/development/embeddings-server.md。运行 embeddings 容器docker run -d --name baserow-embeddings -p 80:80 baserow/embeddings:latest让 Baserow 指向它BASEROW_EMBEDDINGS_API_URLhttp://your-embedder-service # e.g., http://localhost if you mapped -p 80:80 locally # Then restart Baserow and allow migrations to run.重启并等待迁移完成后知识库检索即可用。该变量在后端配置中的读取点见 backend/src/baserow/config/settings/base.py。从 embeddings-server.md 可以看到embeddings 服务启动后还需执行一次知识导入宿主机执行just dcd run --rm backend manage sync_knowledge_base容器内为./baserow sync_knowledge_base它会调度任务导入website_export.csv中的全部文档并生成本地 embeddings。完成后助手使用search_docs工具时 UI 会出现 “Exploring the knowledge base...” 提示回答会附带文档来源。该文档还提示了两类典型故障Kuma 不出现在侧边栏检查 backend 与 frontend 的BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL以及 Kuma 可见但不检索文档重跑sync_knowledge_base。5. 故障排查助手不出现或不工作若助手在侧边栏不可见或不可用请确认满足以下两种配置之一在AI providers AI features中选中一个可用的 Kuma 模型且其模型测试通过或Kuma 选择保持未配置并在 backend 与 frontend 两个服务中都设置遗留BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL同时其 provider 凭据对 backend 可用。注意显式禁用 Kuma 不会使用遗留回退。从源码结构看模型可用性在每次请求前还会经过一道缓存的“就绪检查”check_lm_ready_or_raiselegacy/explicit 来源做进程本地探测同一进程内一个模型同时只探一次失败结果短 TTL 缓存 30 秒database 来源则使用全局缓存成功缓存 300 秒、失败 30 秒探测内容即文本响应加 tool calling 测试。探测失败会包装为AssistantModelNotSupportedErrorlegacy/explicit或AssistantConfiguredModelNotAvailableErrordatabase这解释了为什么“模型测试不通过”会直接导致助手不响应。开发环境验证遗留环境变量在宿主机检查变量是否正确设置# Check backend just dcd run --rm backend bash -c env | grep LLM_MODEL just dcd run --rm backend bash -c env | grep API_KEY # Check frontend just dcd run --rm web-frontend bash -c env | grep LLM_MODEL两条命令必须返回相同的BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL值任一侧缺失或不一致时更新环境配置并重启服务。6. 受支持的模型OpenAI、Anthropic、AWS Bedrock、Groq、Gemini/Vertex AI以及任意 OpenAI 兼容端点Azure、DeepSeek、Fireworks、LiteLLM、Perplexity、Together AI 等。7. 框架迁移UDSPy 到 pydantic-ai助手此前使用 UDSPy 作为 Agent 框架现已切换为 pydantic-ai。大部分环境变量保持不变或已做向后兼容桥接。保持不变的变量变量说明BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL在数据库选择未配置或无效时继续作为回退显式禁用时不生效。provider/model与provider:model两种格式均可接受。BASEROW_ENTERPRISE_ASSISTANT_LLM_TEMPERATURE仍受支持。设置时覆盖编排器 temperature。OPENAI_API_KEY不变。GROQ_API_KEY不变。AWS_BEARER_TOKEN_BEDROCK仍可用——pydantic-ai 原生支持 Bedrock bearer token 认证。已桥接、无需处理旧变量等价于说明UDSPY_LM_MODELBASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL若已设置且新变量缺失旧值自动生效后端见 settings.py前端见 env-remap.mjs。UDSPY_LM_API_KEYOPENAI_API_KEY/GROQ_API_KEY/ 等作为回退传播到所有 provider 密钥变量桥接发生在模型创建时见 retrying_model.py 中的凭据解析。UDSPY_LM_OPENAI_COMPATIBLE_BASE_URLOPENAI_BASE_URL仍可用自动桥接。AWS_REGION_NAMEAWS_DEFAULT_REGION仍可用自动桥接settings.py 中通过os.environ.setdefault实现。新增变量变量说明OPENAI_BASE_URLUDSPY_LM_OPENAI_COMPATIBLE_BASE_URL的推荐替代。AWS_DEFAULT_REGIONAWS_REGION_NAME的推荐替代。OLLAMA_BASE_URLOllama 场景下替代UDSPY_LM_OPENAI_COMPATIBLE_BASE_URL默认http://localhost:11434/v1。ANTHROPIC_API_KEY新提供商——现在支持 Anthropic 模型。模型字符串的归一化由_normalize_model_string完成provider/model会转换为provider:model不带前缀的裸模型名默认补上openai:前缀——这就是文档所说“两种格式均可接受”的实现依据。8. 小结Baserow AI 助手的启用可以归纳为一条清晰的决策链优先数据库化 AI Providerai-providers特性 Admin UI 选 Kuma 模型显式禁用最高优先遗留环境变量BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL仅作回退且需同时配置于 backend 与 frontend凭据走 pydantic-ai 各 provider 的标准环境变量知识库检索则依赖独立的 embeddings 服务与sync_knowledge_base导入。理解 model_profiles.py 中的解析与就绪检查逻辑后排障时可以把“侧边栏不出现助手”“模型测试失败”“草稿未发布”这几类现象快速对号入座。【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考