john
150 lines
7.0 KiB
Markdown
150 lines
7.0 KiB
Markdown
# image_make 隔离接入
|
||
|
||
## 边界
|
||
|
||
`image_make` 是独立服务。Memind 只通过 HTTP API 调用，下载结果并校验后写入 MindSpace；
|
||
`image_make` 不连接 Memind 数据库，也不能直接写 MindSpace。开关关闭或请求失败时，现有页面、
|
||
封面与缩略图流程保持不变。
|
||
|
||
## 后台开关
|
||
|
||
开关位于 `memind_adm` 的「资产能力」页面，按以下顺序生效：
|
||
|
||
1. 资产能力总开关开启；
|
||
2. 图片生成插件开启，Provider 选择 `image_make`；
|
||
3. 单独开启需要的用途：页面正文图片、页面头图、卡片封面、信息流与缩略图源图；
|
||
4. Memind 运行环境同时配置 `IMAGE_MAKE_BASE_URL` 与 `IMAGE_MAKE_TOKEN`。
|
||
|
||
所有开关默认关闭。信息流缩略图仍由 MindSpace 从 `feed_cover` canonical 源资产派生，禁止为了
|
||
缩略图再次调用生图模型。
|
||
|
||
Provider、默认模型、超时和 ComfyUI 参数由 MemindAdm 的图片生成配置写入 Portal 数据库。
|
||
百炼密钥优先复用「统一模型中心」中已启用的 DashScope/Qwen 视觉 Provider；管理接口只返回
|
||
脱敏状态，不返回明文密钥。
|
||
|
||
独立 `image_make` 服务通过下列内部接口拉取运行配置：
|
||
|
||
```http
|
||
GET /api/internal/image-make/runtime-config
|
||
Authorization: Bearer <IMAGE_MAKE_TOKEN>
|
||
```
|
||
|
||
该接口会把运行时所需的 Provider 配置返回给受信任的 `image_make` 服务，因此必须只在内网使用，
|
||
并保证 Portal 与 `image_make` 配置相同的 Token。
|
||
|
||
## Memind API
|
||
|
||
登录用户可显式调用：
|
||
|
||
```http
|
||
POST /api/mindspace/v1/images/generate
|
||
Idempotency-Key: imgreq_xxx
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"purpose": "hero",
|
||
"prompt": "无文字的安静未来阅读空间，暖色自然光"
|
||
}
|
||
```
|
||
|
||
`purpose` 可选值：`inline_image`、`hero`、`card_cover`、`feed_cover`。
|
||
|
||
成功时服务先完成以下步骤，再返回 `201`：
|
||
|
||
1. 创建并轮询 image_make 任务；
|
||
2. 下载图片并校验 MIME、文件头、大小与 SHA-256；
|
||
3. 通过现有 `createChatAsset` 写入用户 MindSpace 公共候选资产；
|
||
4. 获得 canonical `publicUrl` 后 best-effort acknowledge image_make 临时结果。
|
||
|
||
开关关闭返回带 `fallback: true` 的 `409`；服务未配置或暂不可用返回带 `fallback: true` 的
|
||
`503`。调用方必须继续原有页面或默认缩略图流程。
|
||
|
||
## 本地配置
|
||
|
||
```bash
|
||
IMAGE_MAKE_BASE_URL=http://127.0.0.1:8080
|
||
IMAGE_MAKE_TOKEN=dev-token
|
||
IMAGE_MAKE_REQUEST_TIMEOUT_MS=15000
|
||
IMAGE_MAKE_GENERATION_TIMEOUT_MS=600000
|
||
IMAGE_MAKE_POLL_INTERVAL_MS=1000
|
||
IMAGE_MAKE_MAX_RESULT_BYTES=20971520
|
||
IMAGE_MAKE_SEMANTIC_REVIEW_ENABLED=1
|
||
IMAGE_MAKE_SEMANTIC_REVIEW_MIN_SCORE=70
|
||
IMAGE_MAKE_SEMANTIC_REVIEW_MAX_ATTEMPTS=3
|
||
```
|
||
|
||
Token 只进入 Memind 运行环境，不在 `memind_adm` 页面或数据库中保存、展示。
|
||
|
||
页面 Agent 通过 sandbox MCP 的 `generate_image` 工具调用 Portal 内部入口。需要额外配置
|
||
`MINDSPACE_AGENT_API_BASE_URL`；MCP 使用现有 `MINDSPACE_INTERNAL_AGENT_SECRET` 鉴权，成功结果
|
||
直接返回 MindSpace `publicUrl` 与 `workspaceRelativePath`。工具始终受同一后台总开关、Provider
|
||
开关和用途开关约束。容器部署时 base URL 应使用容器可访问的 Portal 地址，不能使用容器自身的
|
||
`127.0.0.1`。
|
||
|
||
`image_make` 服务还需配置：
|
||
|
||
```bash
|
||
AUTH_TOKEN_MEMIND=<与 Portal IMAGE_MAKE_TOKEN 相同的值>
|
||
IMAGE_MAKE_MEMIND_CONFIG_URL=http://<portal-host>:8081/api/internal/image-make/runtime-config
|
||
IMAGE_MAKE_MEMIND_CONFIG_TOKEN=<与 Portal IMAGE_MAKE_TOKEN 相同的值>
|
||
```
|
||
|
||
## 语义审核
|
||
|
||
生成结果写入 MindSpace 前默认调用统一模型中心配置的 Qwen VL/DashScope 视觉模型做图文一致性
|
||
审核。审核不可用、返回格式无效或相关度低于阈值时均 fail closed，不保存图片；语义不匹配最多
|
||
重试三次，并为每次重试使用新的幂等键。生产启用图片生成前必须同时验证生图 Provider 与视觉
|
||
审核 Provider，不能只验证 `/health`。
|
||
|
||
## 微信服务号聊天与页面策略
|
||
|
||
服务号通道使用独立的图片策略，不改变 H5 输入区现有的 `auto / required / disabled` 三态：
|
||
|
||
1. 服务号普通聊天只有在用户明确要求“生成图片 / 生图 / 画一张”等意图时，才强制加载
|
||
`image-generation` 并调用一次 `generate_image(purpose=inline_image)`；用户明确说不要图片时禁止调用。
|
||
2. 服务号生成的每个正式用户内容页面，默认必须在本轮生成一张新的缩略图源图。优先调用一次
|
||
`generate_image(purpose=hero)`，页面 Hero、`mindspace-cover.cover` 与后续缩略图派生复用这张图，
|
||
禁止为了卡片或信息流再次调用 `card_cover` / `feed_cover`。
|
||
3. 正文独立插图与缩略图策略分离：只有用户明确要求正文配图，或正文确有不同画面需求时才调用
|
||
`inline_image`。用户说“不要图片”时，正文与 Hero 不展示图片，但正式页面仍保留新的缩略图源图。
|
||
4. 管理后台、密码查看、重定向、下载包装和错误辅助页不要求单独生图。
|
||
5. 页面交付前必须确认 `mindspace-cover.cover` 引用当前轮工具返回的 `asset.htmlSrc`；历史 `jobId`、
|
||
旧图、默认渐变和占位路径均不能满足交付条件。验证失败时保留草稿但禁止发送页面链接。
|
||
6. 独立生成图片会转换为微信可接受的 JPEG，上传临时图片素材后以原生图片客服消息发送；素材上传
|
||
失败时降级发送 MindSpace 公网图片链接。
|
||
|
||
配置 `H5_WECHAT_MP_FRESH_PAGE_THUMBNAILS=0` 可只关闭服务号“页面必须新缩略图”硬门，作为紧急回滚；
|
||
默认开启。该开关不会修改 H5 聊天图片策略。
|
||
|
||
配置 `H5_WECHAT_MP_FRESH_THUMBNAIL_REPAIR=1` 可开启服务号缩略图确定性修复，默认关闭。修复仅在一个正式页面
|
||
与一张本轮 hero 图片的映射唯一时，把本轮 `asset.htmlSrc` 写回 `mindspace-cover.cover` 并重新执行完整校验；
|
||
多页、多图、缺少本轮新图或元数据无效时继续 fail closed。
|
||
|
||
## 发布前置条件
|
||
|
||
Portal runtime 不包含独立 `image_make` 服务。正式启用前必须确保：
|
||
|
||
1. `image_make` 来自独立、可追溯的 Git commit 和发布产物；
|
||
2. 服务已在目标环境启动，`/health` 与 `/ready` 均通过；
|
||
3. Portal 与服务端 Token 一致，运行配置接口可从服务侧访问；
|
||
4. MemindAdm 中 Provider、用途开关和统一模型中心 DashScope Key 已配置；
|
||
5. 使用真实图片请求完成生成、语义审核、MindSpace 落盘和页面引用的端到端验收。
|
||
|
||
若这些条件未完成，保持所有图片用途开关关闭；不得把 Portal 代码已上线等同于图片生成能力已
|
||
可用。
|
||
|
||
相关代码改动至少执行：
|
||
|
||
```bash
|
||
npm test
|
||
npm run build
|
||
npm run verify:mindspace-publish-guards:full
|
||
npm run verify:mindspace-page-sync-guards
|
||
npm run verify:h5-session-patches
|
||
```
|
||
|
||
## 回滚
|
||
|
||
在 `memind_adm` 关闭图片生成插件或资产能力总开关即可立即停止新调用。该回滚不删除已经入库
|
||
的 MindSpace 图片，不要求回滚数据库字段，也不改变既有页面内容。
|