Deeplake 托管服务 SDK 是一个面向智能体友好的数据写入工具，用于将数据写入 Deeplake 托管表。当用户希望在 Deeplake 中存储、写入或查询数据时可以使用本技能。SDK 同时提供 Python 和 Node.js/TypeScript 两个版本。
一、用途 本 SDK 用于将数据写入 Deeplake 托管表，并支持对已写入数据进行查询、向量检索与文本检索。所有数据库操作均通过 REST API 完成，不建立直接的 PostgreSQL 连接；数据集访问使用 al:// 路径并自动解析凭证。
二、主要能力
- 数据写入：支持文件写入（schema 中列类型为 FILE）、结构化数据写入（字典形式，列数据自动推断 schema）、显式 schema 写入、HuggingFace 数据集导入（{"_huggingface": "name"}）、以及通过格式对象写入（如 CocoPanoptic、Coco、LeRobot 或自定义格式）。
- 文件分块策略：视频按 10 秒分段并生成缩略图；图片单块；PDF 按页以 150 DPI 渲染（可通过 pdf_dpi 配置）；文本按 1000 字符分块、200 字符重叠；其他类型为单个二进制块。
- 表管理：create_table 创建空表、list_tables、drop_table、create_index、drop_index、describe_table、open_table。
- 查询：支持链式查询（select/where/limit）与原生 SQL；向量相似度使用 embedding::float4[] <#> query_vec；BM25 文本搜索使用 text <#> 'search query'；混合搜索使用 (embedding, text)::deeplake_hybrid_record。
- 训练与流式读取：open_table 返回原生 deeplake.Dataset，可配合 PyTorch DataLoader、TensorFlow tf.data.Dataset 及批量迭代使用。
三、使用方式 Python：pip install deeplake（或 uv add deeplake），从 deeplake 导入 Client；异步变体需安装 aiohttp 后从 deeplake.managed 导入 AsyncClient。Client 支持 token、workspace_id、api_url、org_id 参数，token 可回退到 DEEPLAKE_API_KEY 环境变量。 Node.js/TypeScript：npm install deeplake，从 deeplake 导入 ManagedClient 与 initializeWasm；在任何操作前必须先调用一次 await initializeWasm()。ManagedClient 接受 token、workspaceId、apiUrl。 API 令牌可在 Deeplake 平台创建，令牌为内嵌 org_id 的 JWT。跨组织调用时需传入 org_id（或设置 ACTIVELOOP_ORG_ID），SDK 会以 X-Activeloop-Org-Id 请求头转发。
四、适用场景 需要将视频、图片、PDF、文本等文件批量写入并自动分块；需要写入带向量或文本索引的结构化数据以支持检索；需要从 HuggingFace 导入数据集；需要在训练循环中流式读取托管表并接入 PyTorch/TensorFlow。
五、限制与注意事项
- 需要 Deeplake API 服务运行（默认 https://api.deeplake.ai）。
- 可选依赖按文件类型安装：视频需 ffmpeg；PDF 需 pymupdf（Python）或 pdfjs-dist（Node.js）；缩略图需 Pillow（Python）或 sharp（Node.js）；COCO 检测格式需 pycocotools、Pillow、numpy；LeRobot 帧格式需 pandas、numpy。
- ingest 为追加写入：若表已存在则追加数据而非重建，需先 drop_table 才能替换；追加数据的 schema 必须兼容。
- 应始终核对返回的 row_count 是否等于发送的数据量，不能仅以未报错作为写入成功的依据；大批量写入后可用 SELECT COUNT(*) 确认，但需注意可见性延迟。
- 同时提供 data 与 format 时 format 优先，data 被忽略；两者都未提供会抛出 IngestError。
- 仅读取时应传 read_only=True，默认读写模式会获取写句柄。
- 通过 client.query() 进行向量相似度搜索时，向量必须内联而非以 $1 传参。
- 创建表时 EMBEDDING 类型需保留维度（如 EMBEDDING(1536)），不能使用裸 EMBEDDING。
- Python 客户端无 close() 方法，为无状态设计。
- 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。