🦞 Gradient AI — 知识库与 RAG

⚠️ 本技能为非官方社区开发，由 DigitalOcean 不维护。使用需自行承担风险。

*"龙虾从不遗忘。你的智能体也不应遗忘。" —— 知识库龙虾*

利用 DigitalOcean 的 Gradient 知识库构建 [检索增强生成](https://docs.digitalocean.com/products/gradient-ai-platform/details/features/#retrieval-augmented-generation-rag) 流水线。将文档存储在 DO Spaces 中，将其索引到托管式知识库（基于 OpenSearch），并通过语义或混合搜索进行查询。

架构

你的智能体                   DigitalOcean
┌─────────────┐     上传      ┌──────────────┐
│  文档文件   │ ──────────▶  │  DO Spaces   │
└─────────────┘              │  (S3 兼容)   │
                              └──────┬───────┘
                                     │ 自动索引
                              ┌──────▼───────┐
                              │ 知识库 (KBaaS) │
                              │ ┌──────────┐ │
                              │ │OpenSearch│ │
                              │ └──────────┘ │
                              └──────┬───────┘
                                     │ 检索
┌─────────────┐     回答        ┌──────▼───────┐
│  你的智能体 │ ◀──────────  │  RAG 结果    │
│  + LLM      │              │  + 引用信息  │
└─────────────┘              └──────────────┘

📖 *[知识库文档](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/create-manage-knowledge-bases/)*

API 端点

该技能连接至 DigitalOcean 三个官方服务端点：

所有端点均由 DigitalOcean 所有并运营。*.do-ai.run 域名为 Gradient AI 平台的服务域名。

认证

该技能使用 两种不同的凭证 —— 可以理解为双钳策略：

凭证权限最小化原则： 使用权限最小的令牌。为 GRADIENT_API_KEY 创建专用的 [模型访问密钥](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/manage-access-keys/)。对于 DO_API_TOKEN，使用具有仅知识库和 Spaces 权限的 [受限 API 令牌](https://docs.digitalocean.com/reference/api/create-personal-access-token/)。避免使用账户根令牌。

可选但推荐设置：

export GRADIENT_KB_UUID="your-kb-uuid"     # 默认用于查询的知识库 UUID
export DO_SPACES_BUCKET="your-bucket"      # 默认用于上传的存储桶
export DO_SPACES_ENDPOINT="https://nyc3.digitaloceanspaces.com"

工具

📦 将文档存入 Spaces

将文件上传至 DO Spaces，供知识库索引使用。这是存储层 —— 文档在此处落地后才会被索引。

# 上传文件
python3 gradient_spaces.py --upload /path/to/report.md --bucket my-kb-data

# 上传并指定键前缀（模拟文件夹结构）
python3 gradient_spaces.py --upload report.md --bucket my-kb-data --prefix "research/2026-02-15/"

# 列出存储桶中的文件
python3 gradient_spaces.py --list --bucket my-kb-data

# 使用前缀过滤列出文件
python3 gradient_spaces.py --list --bucket my-kb-data --prefix "research/"

# 删除文件
python3 gradient_spaces.py --delete "research/old_report.md" --bucket my-kb-data

📖 *[DO Spaces 文档](https://docs.digitalocean.com/products/spaces/)*

🏗️ 创建与管理知识库

支持知识库的完整增删改查操作。可通过程序化方式创建，无需像陆地生物一样在控制台点击操作。

# 列出所有知识库
python3 gradient_kb_manage.py --list

# 创建新知识库
python3 gradient_kb_manage.py --create --name "我的研究知识库" --region nyc3

# 查看特定知识库详情
python3 gradient_kb_manage.py --show --kb-uuid "your-kb-uuid"

# 删除知识库（⚠️ 永久性删除！）
python3 gradient_kb_manage.py --delete --kb-uuid "your-kb-uuid"

📖 *[通过 API 创建知识库](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/create-manage-knowledge-bases/)*

📁 管理数据源

将您的 DO Spaces 存储桶（或网页 URL）连接到知识库。这一步告诉知识库“请索引这些文档”。

# 添加 DO Spaces 数据源
python3 gradient_kb_manage.py --add-source \
  --kb-uuid "your-kb-uuid" \
  --bucket my-kb-data \
  --prefix "research/"

# 列出某个知识库的数据源
python3 gradient_kb_manage.py --list-sources --kb-uuid "your-kb-uuid"

# 触发重新索引（自动检测数据源）
python3 gradient_kb_manage.py --reindex --kb-uuid "your-kb-uuid"

# 为特定数据源触发重新索引
python3 gradient_kb_manage.py --reindex --kb-uuid "your-kb-uuid" --source-uuid "ds-uuid"

🦞 小贴士：自动索引。 如果知识库启用了自动索引功能，可跳过手动触发重索引。知识库会自动检测 DO Spaces 存储桶中的变更。可在 [DigitalOcean 控制台](https://cloud.digitalocean.com) → 知识库 → 设置 中配置。

🔍 查询知识库

Skill: Gradient Knowledge Base

Version: 0.1.4

Chunk: 2/2

使用语义或混合查询检索已索引的文档。这里就是魔法发生的地方——你的文档将转化为答案。

# 基础查询
python3 gradient_kb_query.py --query "Q4 财务报告发生了什么？"

# 控制返回结果数量
python3 gradient_kb_query.py --query "收入趋势" --num-results 20

# 调整混合搜索平衡（见下文）
python3 gradient_kb_query.py --query "$CAKE 价格走势" --alpha 0.5

# JSON 输出（用于与其他工具管道连接）
python3 gradient_kb_query.py --query "SEC 文件摘要" --json

直接 API 调用：

curl -s https://kbaas.do-ai.run/v1/{kb-uuid}/retrieve \
  -H "Authorization: Bearer $DO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Q4 财务报告发生了什么？",
    "num_results": 10,
    "alpha": 0.5
  }'

📖 *[KB 检索 API 文档](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/create-manage-knowledge-bases/#query-a-knowledge-base)*

🎛️ alpha 参数 — 混合搜索调优

这是关键所在。alpha 参数控制关键词（字面）与语义（含义）搜索之间的平衡：

🦞 捕蟹法则： 初始建议设为 0.5。若搜索特定内容（如 $CAKE、10-K、2026-02-15），可降低数值；若探索概念（如“市场情绪如何？”），则提高数值。

🧠 RAG 增强型查询

完整流程：查询知识库 → 构建上下文提示 → 调用大模型生成综合回答。一条命令，即可获得带引用的答案。

python3 gradient_kb_query.py \
  --query "汇总所有关于 $CAKE 的研究" \
  --rag \
  --model "openai-gpt-oss-120b"

该命令自动完成以下步骤：

1. 🔍 查询知识库以获取相关文档
2. 📝 使用检索到的内容构建提示词
3. 🤖 调用大模型生成最终回答

注意： RAG 查询会调用 [Gradient 推理 API](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/use-serverless-inference/)，因此需要设置 GRADIENT_API_KEY。如果你已加载 gradient-inference 技能，则无需额外配置。

高级配置

嵌入模型与分块策略

创建知识库时，可选择文档的分块方式：

可在 [DigitalOcean 控制台](https://cloud.digitalocean.com) 创建知识库时配置，或通过 API 的 embedding_model 和分块参数设置。

📖 *[知识库配置选项](https://docs.digitalocean.com/products/gradient-ai-platform/details/features/#retrieval-augmented-generation-rag)*

CLI 参考

所有脚本均支持 --json 参数，输出机器可读格式。

gradient_spaces.py      --upload FILE | --list | --delete KEY
                        [--bucket NAME] [--prefix PATH] [--key KEY] [--json]

gradient_kb_manage.py   --list | --create | --show | --delete
                        | --list-sources | --add-source | --reindex
                        [--kb-uuid UUID] [--source-uuid UUID]
                        [--name NAME] [--region REGION] [--bucket NAME]
                        [--prefix PATH] [--json]

gradient_kb_query.py    --query TEXT [--kb-uuid UUID] [--num-results N]
                        [--alpha F] [--rag] [--model ID] [--json]

环境变量

外部接口地址

安全与隐私

• 你的 DO_API_TOKEN 将作为 Bearer Token 发送到 api.digitalocean.com 和 kbaas.do-ai.run
• Spaces 凭据用于向 {region}.digitaloceanspaces.com 上传数据
• 上传至 Spaces 的文档默认为私有
• 知识库查询仅限于你的账户，无跨租户访问
• 不会将任何凭据或数据发送至第三方服务

信任声明

使用此技能意味着你将文档和查询发送至 DigitalOcean 的知识库与 Spaces API。请仅在信任 DigitalOcean 处理你所索引文档的前提下安装。

重要提示

• 上传至 Spaces 的文档默认为私有
• 重新索引为尽力而为——若 API 调用失败，系统将在后续自动调度索引
• 检索 API 返回的是文档片段，而非完整文档
• 删除知识库为永久操作——索引数据将被彻底清除。但源文件在 Spaces 中不受影响