@acosmi/sdk-ts 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to `@acosmi/sdk-ts` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.10.0] - 2026-06-20 — 多模态向量 / 重排序 (qwen3-vl-embedding / qwen3-vl-rerank)
+
+向量与重排序端点扩展为**多模态**（text / image / **video**），对接 DashScope `qwen3-vl-embedding`（多模态向量端点）与 `qwen3-vl-rerank`（原生 rerank 端点 + 多模态 content）。面向自建搜索引擎的图文 / 视频检索场景。计费口径不变（`total_tokens` 套 input 费率），上游模型名仍由管理员后台自填，不在 SDK / 网关硬编码。
+
+### Added
+
+- **`EmbeddingRequest.contents`** — 多模态向量输入：`MultimodalContent[]`（`{ text?, image?, video? }`）。与 `input`（文本线路）二选一；多模态托管模型用 `contents`。同时新增可选 `output_type` / `fps` / `enable_fusion` 参数。
+- **`RerankRequest` 多态 query / documents** — `query: RerankQuery`（`string | { text?, image? }`），`documents: RerankDocument[]`（`(string | { text?, image?, video? })[]`）；新增可选 `fps`（多模态视频文档抽帧率）。文本调用完全向后兼容（仍可传 `string` / `string[]`）。
+- **类型** — `MultimodalContent` / `RerankQuery` / `RerankDocument`。
+
+### Changed
+
+- **`EmbeddingRequest.input` 改为可选**（`input?: string | string[]`）——多模态线路改用 `contents`。文本调用方无需改动（仍可只传 `input`）。
+
 ## [2.9.0] - 2026-06-20 — 向量 (Embedding) + 重排序 (Rerank) 端点 + listModels 全集模式
 
 托管模型网关新增向量与重排序两类模型（上游接阿里云百炼 DashScope），SDK 订阅会员可经现有会员计费体系（Hold→Settle→Release，按 `total_tokens` 套 input 费率）直接调用。具体上游模型名（`text-embedding-v4` / `gte-rerank-v2` / `qwen3-rerank` 等）由管理员在托管模型后台自填，不在 SDK / 网关硬编码。

package/README.md

@@ -215,6 +215,28 @@ for (const r of resp.results) {
 
 > 重排序对外是**统一扁平契约**；网关内部按模型绑定的线路（DashScope 原生嵌套 `gte-rerank-v2` / OpenAI 兼容扁平 `qwen3-rerank`）自动转换并归一化响应，SDK 侧无需关心。
 
+### 多模态向量 / 重排序（v2.10+，text / image / video）
+
+对接 DashScope `qwen3-vl-embedding`（多模态向量）与 `qwen3-vl-rerank`（多模态重排序）。向量用 `contents` 取代 `input`；重排序的 `query` / `documents` 接受多模态对象（`{ text? , image?, video? }`）。适用于自建搜索引擎的图文 / 视频检索。
+
+```ts
+// 多模态向量：图 / 视频 / 文本混合
+const emb = await client.embeddings(mmEmbModel!.id, {
+  contents: [{ text: '一只橘猫' }, { image: 'https://…/cat.png' }, { video: 'https://…/clip.mp4' }],
+  output_type: 'dense', // 可选
+  fps: 2,               // 可选：视频抽帧率
+});
+
+// 多模态重排序：query 与候选可为多模态对象，也可混入纯文本字符串
+const rr = await client.rerank(mmRerankModel!.id, {
+  query: { text: '红色跑车' },
+  documents: [{ image: 'https://…/car.png' }, { video: 'https://…/road.mp4' }, '一段描述文字'],
+  fps: 1.5, // 可选
+});
+```
+
+> 文本调用完全向后兼容：`input` / 字符串 `query` / 字符串 `documents` 行为不变。多模态托管模型须由管理员在后台勾选对应能力位与输入模态（text/image/video）。
+
 ## 双格式红线（设计核心）
 
 SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应两个不同下游产品。

package/dist/browser/index.mjs

@@ -2206,9 +2206,16 @@ var Client = class _Client {
   fetchImpl;
   /** 互斥锁 (TS 用 Promise chain 替代 sync.Mutex) */
   mu = Promise.resolve();
-  /** WebSocket 状态 (实际方法由 ws.ts mixin 维护) */
+  /**
+   * WebSocket 状态 (实际方法由 ws.ts mixin 维护)。
+   * @internal — 实现细节: 跨模块 (ws.ts mixin) 需可见故为 public, 但非消费者 API,
+   * 消费者用 connect/subscribe 等高层方法; 引用的 WSState 不进公开文档。
+   */
   ws = null;
-  /** v0.15.1: token 就绪等待机制 — login 成功后 resolve, 等待方解除阻塞 */
+  /**
+   * v0.15.1: token 就绪等待机制 — login 成功后 resolve, 等待方解除阻塞。
+   * @internal — 内部同步原语 (Deferred), 非消费者 API。
+   */
   tokenReady = newDeferred();
   /** Login 进行中 — 等待方需等而非 fail-fast */
   loginInFlight = false;