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 实例

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

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

选项 B：商业 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.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 是否可从您的 Canopy 实例访问。