跳到主要内容

AI 功能

AI 建议设置

Canopy 包含由 AI 驱动的功能，使用大型语言模型（LLM） 来协助用户。所有 AI 功能共享一个AI 提供商配置 —— 一次设置，处处使用。

当前可用的 AI 功能：

  • 描述建议 —— 使用网络搜索 + LLM 自动生成卡片描述
  • 投资组合洞察 —— 按需生成应用投资组合的战略分析
  • BPMN 图表生成 —— 从自然语言描述生成和修改 BPMN 2.0 流程图

这些功能是可选的且完全由管理员控制。它们可以使用本地 Ollama 实例完全在您自己的基础设施上运行，也可以连接到商业 LLM 提供商。

工作原理​

AI 建议流程有两个步骤：

  1. 网络搜索 —— Canopy 使用卡片的名称和类型作为上下文查询搜索提供商（DuckDuckGo、Google Custom Search 或 SearXNG）。例如，名为「SAP S/4HANA」的应用程序卡片会生成「SAP S/4HANA 软件应用程序」的搜索。

  2. LLM 提取 —— 搜索结果连同类型感知的系统提示一起发送给配置的 LLM。模型生成描述、置信度评分（0-100%）并列出使用的来源。

结果以以下形式展示给用户：

  • 一个可编辑的描述，可以在应用前查看和修改
  • 一个置信度徽章，显示建议的可靠程度
  • 来源链接，以便用户验证信息

支持的 LLM 提供商​

提供商类型配置
Ollama自托管提供商 URL（例如 http://ollama:11434）+ 模型名称
OpenAI商业API 密钥 + 模型名称（例如 gpt-4o）
Google Gemini商业API 密钥 + 模型名称
Azure 托管的 OpenAI商业API 密钥 + Azure 资源端点 + 部署名称 + API 版本（默认 2025-01-01）
OpenRouter商业API 密钥 + 模型名称
Anthropic Claude商业API 密钥 + 模型名称

商业提供商需要 API 密钥，该密钥使用 Fernet 对称加密存储在数据库中。

搜索提供商​

提供商设置说明
DuckDuckGo无需配置默认。零依赖 HTML 抓取。无需 API 密钥。
Google Custom Search需要 API 密钥和自定义搜索引擎 ID在搜索 URL 字段中以 API_KEY:CX 格式输入。结果质量更高。
SearXNG需要自托管的 SearXNG 实例 URL注重隐私的元搜索引擎。JSON API。

设置​

选项 A：捆绑 Ollama（Docker Compose）​

最简单的入门方式。Canopy 在其 Docker Compose 配置中包含一个可选的 Ollama 容器。

1. 使用 AI 配置文件启动：

docker compose --profile ai up --build -d

2. 启用自动配置，在 .env 中添加以下变量：

AI_AUTO_CONFIGURE=true
AI_MODEL=gemma3:4b          # 或 mistral、llama3:8b 等

启动时，后端将：

  • 检测 Ollama 容器
  • 将连接设置保存到数据库
  • 如果配置的模型尚未下载，则拉取该模型（在后台运行，可能需要几分钟）

3. 验证：在管理 UI 中，前往设置 > AI 建议确认状态显示为已连接。

选项 B：外部 Ollama 实例​

如果您已在独立服务器上运行 Ollama：

  1. 在管理 UI 中前往设置 > AI 建议。
  2. 选择 Ollama 作为提供商类型。
  3. 输入提供商 URL（例如 http://your-server:11434）。
  4. 点击测试连接 —— 系统将显示可用模型。
  5. 从下拉菜单中选择一个模型。
  6. 点击保存。

选项 C：商业 LLM 提供商​

  1. 在管理 UI 中前往设置 > AI 建议。
  2. 选择您的提供商（OpenAI、Google Gemini、Azure OpenAI、OpenRouter 或 Anthropic Claude）。
  3. 输入您的 API 密钥 —— 存储前将被加密。
  4. 输入模型名称（例如 gpt-4o、gemini-pro、claude-sonnet-4-20250514）。
  5. 点击测试连接进行验证。
  6. 点击保存。

配置选项​

连接后，您可以在设置 > AI 建议中微调此功能：

按卡片类型启用/禁用​

并非每种卡片类型都同样受益于 AI 建议。您可以为每种类型单独启用或禁用 AI。例如，您可以为应用程序和 IT 组件卡片启用它，但对组织卡片禁用，因为组织描述是公司特定的。

搜索提供商​

选择在发送给 LLM 之前使用哪个网络搜索提供商来收集上下文。DuckDuckGo 无需配置即可使用。Google Custom Search 和 SearXNG 需要额外设置（参见上方的搜索提供商表格）。

模型选择​

对于 Ollama，管理 UI 显示 Ollama 实例上当前已下载的所有模型。对于商业提供商，直接输入模型标识符。

使用 AI 建议​

卡片详情上的 AI 建议面板

管理员配置后，具有 ai.suggest 权限的用户（默认授予管理员、BPM 管理员和成员角色）将在卡片详情页面和创建卡片对话框中看到星光按钮。

在现有卡片上​

  1. 打开任何卡片的详情视图。
  2. 点击星光按钮（当该卡片类型启用 AI 时，在描述分区旁边可见）。
  3. 等待几秒钟完成网络搜索和 LLM 处理。
  4. 查看建议：阅读生成的描述，检查置信度评分，验证来源链接。
  5. 如需要可编辑文本 —— 建议在应用前完全可编辑。
  6. 点击应用设置描述，或点击取消放弃。

创建新卡片时​

  1. 打开创建卡片对话框。
  2. 输入卡片名称后，AI 建议按钮变为可用。
  3. 点击它在保存前预填描述。

应用程序特定建议​

对于应用程序卡片，当 AI 在网络搜索结果中找到证据时，还可以建议额外的字段：

  • 商业应用程序 —— 如果找到定价、许可信息或销售联系页面，则会启用
  • 托管类型 —— 根据产品的部署模型建议为 On-Premise、Cloud (SaaS)、Cloud (PaaS)、Cloud (IaaS) 或 Hybrid

这些字段仅在 AI 找到明确证据时才会被建议 —— 不会进行推测。用户可以在应用之前查看和调整这些值。

备注

除了应用程序特定字段外，AI 建议主要生成描述字段。其他卡片类型的自定义字段尚未涵盖。

投资组合洞察​

启用后，应用投资组合报告会显示一个 AI 洞察 按钮。点击该按钮会将当前投资组合视图的摘要（分组、属性分布和生命周期数据）发送给配置的 LLM，后者会返回 3-5 条可操作的洞察。

洞察关注以下方面：

  • 集中风险 — 某个组或状态中的应用过多
  • 现代化机会 — 基于生命周期和托管数据
  • 投资组合平衡 — 子类型、组和属性的多样性
  • 生命周期问题 — 即将到达生命周期终点的应用
  • 成本或复杂性驱动因素 — 基于属性分布

启用投资组合洞察​

  1. 前往设置 > AI > 投资组合洞察。
  2. 开启投资组合洞察。
  3. 点击保存。

权限​

角色访问权限
管理员完全访问：配置 AI 设置、使用建议、生成投资组合洞察和生成 BPMN 图表
BPM 管理员使用建议、生成投资组合洞察和生成 BPMN 图表
成员使用建议、生成投资组合洞察和生成 BPMN 图表
查看者无权访问 AI 功能

三个权限键控制 AI 访问：

  • ai.suggest —— 控制对 AI 描述建议的访问
  • ai.portfolio_insights —— 控制对 AI 投资组合洞察的访问
  • bpm.generate —— 控制对 AI BPMN 图表生成和修改的访问

自定义角色可以通过角色管理页面获得这些权限。

隐私和安全​

  • 自托管选项：使用 Ollama 时，所有 AI 处理都在您自己的基础设施上进行。数据不会离开您的网络。
  • 加密 API 密钥：商业提供商的 API 密钥在存储到数据库之前使用 Fernet 对称加密进行加密。
  • 仅搜索上下文：LLM 接收网络搜索结果和卡片的名称/类型 —— 不包括您的内部卡片数据、关系或其他敏感元数据。
  • 用户控制：每个建议都必须由用户审查并明确应用。AI 永远不会自动修改卡片。

故障排除​

问题解决方案
AI 建议按钮不可见检查是否在设置 > AI 建议中为该卡片类型启用了 AI，以及用户是否拥有 ai.suggest 权限。
「AI 未配置」状态前往设置 > AI 建议完成提供商设置。点击测试连接进行验证。
模型未出现在下拉菜单中对于 Ollama：确保模型已下载（ollama pull model-name）。对于商业提供商：手动输入模型名称。
建议缓慢LLM 推理速度取决于硬件（Ollama）或网络延迟（商业提供商）。较小的模型如 gemma3:4b 比较大的模型更快。
置信度评分低LLM 可能无法通过网络搜索找到足够的相关信息。尝试使用更具体的卡片名称，或考虑使用 Google Custom Search 获取更好的结果。
连接测试失败验证提供商 URL 是否可从后端容器访问。对于 Docker 设置，确保两个容器在同一网络上。

环境变量​

这些环境变量提供初始 AI 配置。通过管理 UI 保存后，数据库设置优先。

变量默认值描述
AI_PROVIDER_URL（空）兼容 Ollama 的 LLM 提供商 URL
AI_MODEL（空）LLM 模型名称（例如 gemma3:4b、mistral）
AI_SEARCH_PROVIDERduckduckgo网络搜索提供商：duckduckgo、google 或 searxng
AI_SEARCH_URL（空）搜索提供商 URL 或 API 凭据
AI_AUTO_CONFIGUREfalse启动时如果提供商可达则自动启用 AI
BPMN_RENDERER_URLhttp://bpmn-renderer:3100Node.js BPMN 渲染器边车服务的内部 URL。在 Cloud Run 或其他边车容器共享 localhost 网络的容器平台上运行时，请设置为 http://localhost:3100。