deeplake-managed

Deeplake Managed 是 Deeplake 托管服务的 SDK，用于将数据摄取到 Deeplake 托管表中，适合需要存储、摄取或查询 Deeplake 数据的场景。SDK 同时提供 Python 和 Node.js/TypeScript 版本。

一、用途 该技能用于向 Deeplake 托管表写入数据，并支持后续查询。用户可用它摄取文件、结构化数据、HuggingFace 数据集或自定义格式数据，也可对已有表执行查询、向量相似度搜索、BM25 文本搜索和混合搜索。

二、主要能力

1. 摄取：支持文件摄取（通过 FILE schema）、结构化列数据摄取、HuggingFace 数据集摄取、格式对象摄取。
2. 文件类型处理：视频按 10 秒分段并生成缩略图；图片单块处理；PDF 按页以 150 DPI 渲染（可通过 pdf_dpi 配置）；文本按 1000 字符分块、200 字符重叠；其他类型作为单个二进制块。
3. 查询：提供链式 Fluent Query API（select、where、order_by、limit、offset）和原生 SQL 查询，支持参数化查询与超时设置。
4. 搜索：支持向量余弦相似度搜索（embedding <#> query_vec）、BM25 文本搜索（text <#> 'search query'）和混合搜索。
5. 表管理：列出表、删除表、创建索引。
6. 训练/流式：通过 open_table() 打开托管表为 deeplake.Dataset，支持批量迭代、PyTorch DataLoader、TensorFlow tf.data.Dataset。

三、使用方式 Python 安装：pip install deeplake（或 uv add deeplake）。导入：from deeplake import Client；异步变体需安装 aiohttp 后 from deeplake.managed import AsyncClient。 Node.js/TypeScript 安装：npm install deeplake。导入：import { ManagedClient, initializeWasm } from 'deeplake'；在任何操作前需调用 await initializeWasm()。 客户端初始化：Python 使用 Client(token, workspace_id, api_url)，token 可回退到 DEEPLAKE_API_KEY 环境变量，workspace_id 默认 "default"，api_url 默认 https://api.deeplake.ai。Node.js 使用 new ManagedClient({ token, workspaceId, apiUrl })，token 必填。 Token 创建：在 Deeplake 平台 https://app.deeplake.ai/<org_name>/workspace/<workspace>/apitoken 创建 API token，该 token 为内嵌 org_id 的 JWT。 摄取示例：client.ingest("videos", {"path": ["video1.mp4"]}, schema={"path": "FILE"})；结构化数据 client.ingest("embeddings", {"text": [...], "embedding": [[...]]}, index=["embedding", "text"])；HuggingFace client.ingest("cifar", {"_huggingface": "cifar10"})。 查询示例：client.table("videos").select("id", "text").where("file_id = $1", "abc").limit(10)()；原生 SQL client.query("SELECT * FROM videos LIMIT 10")。

四、适用场景 适合需要将多模态数据（视频、图片、PDF、文本）摄取到托管表并进行检索、向量搜索或训练流式读取的场景，也适合在 Python 或 Node.js 应用中集成 Deeplake 数据存储与查询能力。

五、限制与依赖 必需服务：Deeplake API 服务器运行（默认 https://api.deeplake.ai）。 可选 Python 依赖：视频摄取需 ffmpeg；PDF 摄取需 pymupdf；缩略图生成需 Pillow；COCO 检测格式需 pycocotools、Pillow、numpy；LeRobot 帧格式需 pandas、numpy。 可选 TypeScript 依赖：视频摄取需 ffmpeg（系统二进制）；PDF 摄取需 pdfjs-dist；缩略图生成需 sharp；COCO 检测格式无外部依赖。 表存在性：若表名已存在，ingest() 会追加数据而非删除重建；如需替换需先调用 drop_table()。 查询默认超时为 60 秒，长查询可通过 timeout/timeoutMs 参数增加。 所有数据库操作均通过 REST API，无直接 PG 连接；数据集访问使用 al:// 路径并自动解析凭证。

六、架构说明 Python 为 Client(token, workspace_id)，Node.js 为 ManagedClient({ token, workspaceId })。ingest 通过 API 创建 PG 表并打开 al://{ws}/{table}；query 通过 POST /workspaces/{id}/tables/query 返回结果；table() 提供链式 SQL 构建器；create_index 执行 CREATE INDEX USING deeplake_index；open_table 使用 deeplake.open("al://{ws}/{table}") 并自动获取凭证；list_tables 通过 GET /workspaces/{id}/tables；drop_table 通过 DELETE /workspaces/{id}/tables/{name}。后端为 REST API -> PostgreSQL + pg_deeplake。凭证端点：GET /api/org/{workspace}/ds/{table}/creds。