From 5748cf303fb3b0bb30732a4d96b331a3d38f9de2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Thu, 24 Sep 2026 19:17:42 +0800 Subject: [PATCH] =?UTF-8?q?=E7=A7=8D=E5=AD=90=E5=AD=97=E6=AE=B5=E7=9A=84?= =?UTF-8?q?=E5=AF=B9=E5=A4=96=E7=B1=BB=E5=9E=8B=E6=94=B9=E6=88=90=E6=99=AE?= =?UTF-8?q?=E9=80=9A=E6=95=B0=E5=AD=97=EF=BC=8C=E4=B8=8D=E5=86=8D=E5=AF=BC?= =?UTF-8?q?=E5=87=BA=20bigint?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - shared-contracts：多视图请求与文生 / 图生参数的 seed 注记从 `bigint | null` 改成 `number | null`，并写明只支持 JS 安全整数范围（2^53-1）内的取值；Rust 侧仍是 `Option`，反序列化行为不变 - packages/shared：重新生成 model3d 绑定，seed 变成 `number | null`，请求体可以直接 JSON 序列化（带 bigint 的请求在 JSON.stringify 阶段必定抛错）；顺带补上此前漏生成的多视图请求文档注释（「多视图生 3D」→「多视图生成 3D」） - docs/technical：在 Tripo Provider 集成方案里写明 seed 为什么按 number 导出、代价是超出 2^53-1 的取值无法从 TS 侧精确构造 --- .../【技术方案】Tripo 3D模型Provider集成-2026-09-18.md | 2 ++ .../model3d/image-to-model/Model3dImageToModelParams.ts | 4 ++-- .../multiview-to-model/Model3dMultiviewToModelRequest.ts | 6 +++--- .../model3d/text-to-model/Model3dTextToModelParams.ts | 6 +++--- .../src/model3d/image_to_model/params.rs | 7 ++++--- .../src/model3d/multiview_to_model/request.rs | 7 ++++--- .../shared-contracts/src/model3d/text_to_model/params.rs | 9 +++++---- 7 files changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md b/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md index 956da6545..8533ba845 100644 --- a/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md +++ b/docs/technical/【技术方案】Tripo 3D模型Provider集成-2026-09-18.md @@ -22,6 +22,8 @@ task 尚未完成时 `output` 为空；完成后 `output` 必须是与 task type 生成结果 DTO 中的 `poll_after_ms`、`updated_at_micros` 与 `size_bytes` 以 TypeScript `number` 导出：毫秒级轮询间隔与几十 MB 的产物字节数远低于 2^53，微秒时间戳在 2^53 内也可精确表示（约到公元 2255 年），因此不做 `bigint`/`string` 特殊处理；若将来出现超过 2^53 的取值再评估。 +生成参数里的 seed（`image_seed`、`model_seed`、`texture_seed`）同样以 TypeScript `number` 导出，不导出成 `bigint`：请求最终是 JSON 文本，JSON 没有大整数类型，带 `bigint` 的请求体在 `JSON.stringify` 阶段就会直接抛错。代价是前端能精确表示的取值上限为 2^53-1（JS 安全整数），超出该范围的种子没法从 TS 侧精确构造；Rust 侧仍按 `i64` 反序列化，手工构造的请求可以传更大取值。 + ## 三个入口的输入 - text-to-model：`prompt` 必填，上限 1024 字符；`negative_prompt` 上限 255 字符。空白 prompt 在提交前拒绝。 diff --git a/packages/shared/src/contracts/model3d/image-to-model/Model3dImageToModelParams.ts b/packages/shared/src/contracts/model3d/image-to-model/Model3dImageToModelParams.ts index 274ad169b..031f12a70 100644 --- a/packages/shared/src/contracts/model3d/image-to-model/Model3dImageToModelParams.ts +++ b/packages/shared/src/contracts/model3d/image-to-model/Model3dImageToModelParams.ts @@ -17,8 +17,8 @@ import type { Model3dTextureVersion } from '../common/Model3dTextureVersion'; export type Model3dImageToModelParams = { model: Model3dModelVersion; enableImageAutofix?: boolean | null; - modelSeed?: bigint | null; - textureSeed?: bigint | null; + modelSeed?: number | null; + textureSeed?: number | null; texture?: boolean | null; pbr?: boolean | null; textureQuality?: Model3dTextureQuality | null; diff --git a/packages/shared/src/contracts/model3d/multiview-to-model/Model3dMultiviewToModelRequest.ts b/packages/shared/src/contracts/model3d/multiview-to-model/Model3dMultiviewToModelRequest.ts index 2d8727fd1..4d8f8aee9 100644 --- a/packages/shared/src/contracts/model3d/multiview-to-model/Model3dMultiviewToModelRequest.ts +++ b/packages/shared/src/contracts/model3d/multiview-to-model/Model3dMultiviewToModelRequest.ts @@ -10,7 +10,7 @@ import type { Model3dTextureVersion } from '../common/Model3dTextureVersion'; import type { Model3dMultiviewInputs } from './Model3dMultiviewInputs'; /** - * 多视图生 3D 的请求：`inputs` 必填，其余生成参数可选。 + * 多视图生成 3D 的请求：`inputs` 必填，其余生成参数可选。 * * 严格反序列化：顶层与 `inputs` 分支都不接受未知字段，字段取值非法在反序列化阶段即拒绝； * 组合合法性（模型能力、参数互斥）由 provider 侧提交前统一校验。 @@ -27,11 +27,11 @@ export type Model3dMultiviewToModelRequest = { /** * 模型随机种子；固定后可复现同一几何体。 */ - modelSeed?: bigint | null; + modelSeed?: number | null; /** * 贴图随机种子；固定后可复现同一贴图。 */ - textureSeed?: bigint | null; + textureSeed?: number | null; /** * 是否生成贴图；`false` 时只产出白模几何体。 */ diff --git a/packages/shared/src/contracts/model3d/text-to-model/Model3dTextToModelParams.ts b/packages/shared/src/contracts/model3d/text-to-model/Model3dTextToModelParams.ts index 68f76b2f1..e8520db02 100644 --- a/packages/shared/src/contracts/model3d/text-to-model/Model3dTextToModelParams.ts +++ b/packages/shared/src/contracts/model3d/text-to-model/Model3dTextToModelParams.ts @@ -16,9 +16,9 @@ export type Model3dTextToModelParams = { prompt: string; model: Model3dModelVersion; negativePrompt?: string | null; - imageSeed?: bigint | null; - modelSeed?: bigint | null; - textureSeed?: bigint | null; + imageSeed?: number | null; + modelSeed?: number | null; + textureSeed?: number | null; texture?: boolean | null; pbr?: boolean | null; textureQuality?: Model3dTextureQuality | null; diff --git a/server-rs/crates/shared-contracts/src/model3d/image_to_model/params.rs b/server-rs/crates/shared-contracts/src/model3d/image_to_model/params.rs index 2780c45ea..2ffcad127 100644 --- a/server-rs/crates/shared-contracts/src/model3d/image_to_model/params.rs +++ b/server-rs/crates/shared-contracts/src/model3d/image_to_model/params.rs @@ -19,11 +19,12 @@ pub struct Model3dImageToModelParams { pub model: Model3dModelVersion, #[ts(optional = nullable)] pub enable_image_autofix: Option, - // seed 是 i64，JS `number` 表示不了全部取值，因此按 bigint 导出，避免静默舍入。 - #[ts(type = "bigint | null")] + // seed 是 i64；对外只按 JSON 数字传递，前端能精确表示的上限是 2^53-1（JS 安全整数）， + // 超出该范围的取值没法在前端精确构造，服务端仍按 i64 反序列化。 + #[ts(type = "number | null")] #[ts(optional = nullable)] pub model_seed: Option, - #[ts(type = "bigint | null")] + #[ts(type = "number | null")] #[ts(optional = nullable)] pub texture_seed: Option, #[ts(optional = nullable)] diff --git a/server-rs/crates/shared-contracts/src/model3d/multiview_to_model/request.rs b/server-rs/crates/shared-contracts/src/model3d/multiview_to_model/request.rs index 3179bc2d7..e3010f93c 100644 --- a/server-rs/crates/shared-contracts/src/model3d/multiview_to_model/request.rs +++ b/server-rs/crates/shared-contracts/src/model3d/multiview_to_model/request.rs @@ -79,13 +79,14 @@ pub struct Model3dMultiviewToModelRequest { pub inputs: Model3dMultiviewInputs, /// 模型版本；决定模型家族与可用的生成能力。 pub model: Model3dModelVersion, - // seed 是 i64，JS `number` 表示不了全部取值，因此按 bigint 导出，避免静默舍入。 + // seed 是 i64；对外只按 JSON 数字传递，前端能精确表示的上限是 2^53-1（JS 安全整数）， + // 超出该范围的取值没法在前端精确构造，服务端仍按 i64 反序列化。 /// 模型随机种子；固定后可复现同一几何体。 - #[ts(type = "bigint | null")] + #[ts(type = "number | null")] #[ts(optional = nullable)] pub model_seed: Option, /// 贴图随机种子；固定后可复现同一贴图。 - #[ts(type = "bigint | null")] + #[ts(type = "number | null")] #[ts(optional = nullable)] pub texture_seed: Option, /// 是否生成贴图；`false` 时只产出白模几何体。 diff --git a/server-rs/crates/shared-contracts/src/model3d/text_to_model/params.rs b/server-rs/crates/shared-contracts/src/model3d/text_to_model/params.rs index 82abb7e24..ffed027bd 100644 --- a/server-rs/crates/shared-contracts/src/model3d/text_to_model/params.rs +++ b/server-rs/crates/shared-contracts/src/model3d/text_to_model/params.rs @@ -19,14 +19,15 @@ pub struct Model3dTextToModelParams { pub model: Model3dModelVersion, #[ts(optional = nullable)] pub negative_prompt: Option, - // seed 是 i64，JS `number` 表示不了全部取值，因此按 bigint 导出，避免静默舍入。 - #[ts(type = "bigint | null")] + // seed 是 i64；对外只按 JSON 数字传递，前端能精确表示的上限是 2^53-1（JS 安全整数）， + // 超出该范围的取值没法在前端精确构造，服务端仍按 i64 反序列化。 + #[ts(type = "number | null")] #[ts(optional = nullable)] pub image_seed: Option, - #[ts(type = "bigint | null")] + #[ts(type = "number | null")] #[ts(optional = nullable)] pub model_seed: Option, - #[ts(type = "bigint | null")] + #[ts(type = "number | null")] #[ts(optional = nullable)] pub texture_seed: Option, #[ts(optional = nullable)]