cuda-webdoc-search

CUDA-X 文档搜索指南

概述

通过查询 Sphinx 库存文件，搜索和发现 CUDA-X 库文档中的 API。需要查找特定 CUDA 库函数、检查可用 API 或获取文档链接时，可使用此技能。

设置

uv tool install "cuda-webdoc-search @ git+https://github.com/ultimatile/cuda-x-skills.git#subdirectory=skills/cuda-webdoc-search"

安装后，cws 可作为独立命令使用。无需安装即可一次性使用：

uvx --from "cuda-webdoc-search @ git+https://github.com/ultimatile/cuda-x-skills.git#subdirectory=skills/cuda-webdoc-search" cws search cublas --stats

适用场景

• 查找 CUDA 库 API（例如：“cuTensorNet 有哪些 SVD 函数？”）
• 检查某个特定函数是否存在于某个库中
• 获取 CUDA API 的文档 URL
• 探索库中可用的操作

快速参考

先检查可用域

搜索前，先检查有哪些可用域（API 类型）：

cws search <library> --stats

这会返回各域的数量：cpp（C++ API）、c（C API）、py（Python 绑定）、std（文档标签）。

搜索 API

cws search <library> --domains <domain> --keywords "<terms>" --fuzzy --limit 20

关键词语法（fzf 子集）

• 空格分隔的词项表示 AND（必须全部匹配）：--keywords "SVD batch"
• 使用 | 表示 OR（需要用 shell 引号括起来）：--keywords "SVD | QR"
• AND 的优先级高于 OR：--keywords "a b | c" = (a AND b) OR c
• 注意：仅支持通过 | 使用 AND/OR。不支持 fzf 运算符 ^、'、!、$。

可用库

完整列表请参阅 registry.toml。常用库包括：

• cuquantum - cuTensorNet、cuStateVec（量子/张量网络）
• cublas - BLAS 运算
• cusolver - 稠密/稀疏求解器
• cusparse - 稀疏矩阵运算
• cufft - FFT 运算
• cudnn - 深度学习基本运算
• cutlass - GEMM 模板
• cuda_math - 数学函数

工作流

1. 确定库：判断 API 可能属于哪个 CUDA 库
2. 检查域：运行 --stats 查看可用的域类型
3. 搜索：使用 --keywords，并搭配 --fuzzy 进行灵活匹配
4. 按域筛选：使用 --domains cpp 搜索 C++ API，使用 --domains c 搜索 C API
5. 提取详情：使用 cws get 获取完整文档内容

示例

在 cuTensorNet 中查找张量分解 API

cws search cuquantum --stats
# Shows: cpp:3179, py:1172, std:3378, c:4

cws search cuquantum --domains cpp --keywords "SVD" --fuzzy --limit 10
# Returns: cutensornetTensorSVD, etc. (functions ranked above enumerators)

cws search cuquantum --domains cpp --keywords "SVD | QR" --fuzzy
# Returns: entries matching SVD OR QR

跨多个库搜索

# "Where is SVD in CUDA-X?" — search cuSOLVER and cuDSS together
cws search cusolver cudss --keywords "svd" --fuzzy --limit 10

# Mix any number of sources
cws search cusolver cusparse cudss --keywords "solve" --fuzzy

多来源输出使用 "sources"（列表）而非 "source"（字符串），并且 "total_found" 会变为按来源区分的字典。

在 cuBLAS 中查找 GEMM 函数

cws search cublas --stats
# Shows: std:36 (only doc labels, no cpp/c domain)

cws search cublas --domains std --keywords "gemm"
# Returns: cublas-t-gemm, cublas-t-gemmex, etc. (doc section labels)

提取 API 文档详情

找到函数 URL 后，提取其完整文档：

cws get <url> --section <function_name>

示例：

cws get \
  "https://docs.nvidia.com/cuda/cuquantum/latest/cutensornet/api/functions.html" \
  --section "cutensornetTensorSVD"

输出为用大括号分隔的文本树：

{
cutensornetTensorSVD
{
cutensornetStatus_t cutensornetTensorSVD {
const cutensornetHandle_t handle
const cutensornetTensorDescriptor_t descTensorIn
...
}
Performs SVD decomposition of a tensor. { ... }
Parameters { ... }
}
}

列出可用来源

cws list                     # table format
cws list --json              # JSON format

审核注册表健康状况

cws audit                    # audit all sources
cws audit --source cublas    # audit single source

输出格式

cws search

JSON 输出包含：

单一来源：

• source：库名称（字符串）
• total_found：经过筛选的域中的 API 总数
• filtered_count：匹配关键词的 API 数量
• candidates：匹配 API 的列表，包含 group（名称）、url、domain、role

多来源（cws search A B）：

• sources：库名称（列表）
• total_found：各来源的总数（字典）
• filtered_count：所有来源中匹配关键词的 API 总数
• candidates：合并后的列表（若使用 --fuzzy，按得分进行 k 路归并；否则直接拼接）

cws get

用大括号分隔的文本树，其中：

• { } 表示层级结构
• 保留文本内容
• 行内元素（代码、链接）会展平为文本

选项：

• --section <id>：仅提取指定章节
• --main-only：仅提取主要内容区域

文件

• cli.py - 统一 CLI 入口（cws）
• search.py - 跨库库存搜索 API
• audit.py - 审核注册表条目的端点健康状况
• get.py - 将文档内容提取为文本树
• fetchers.py - 获取 Sphinx/Doxygen 来源数据
• scoring.py - 搜索排序和筛选逻辑
• registry.py - 注册表加载工具
• registry.toml - 库元数据（URL、文档类型）