astrbot_plugin_imagestudio/backend/services/generation_service.py

2433 行
109 KiB
Python

"""Generation orchestration service."""
from __future__ import annotations
import copy
import threading
from typing import Any
from backend.dto.common import ApiError, ErrorCode
from backend.dto.job_dto import GenerationTask
2026-07-06 02:40:18 +08:00
from backend.services.cost_guard_service import CostGuardService
2026-07-12 02:54:45 +08:00
from backend.services.composition_builder import CompositionBuilder
from backend.services.generation_reference_service import GenerationReferenceService, MaterialResolver
from backend.services.image_service import ImageService
2026-07-06 02:01:45 +08:00
from backend.services.model_provider_service import ModelProviderService
from backend.services.node_dependency_context_service import NodeDependencyContextService
2026-07-06 02:47:37 +08:00
from backend.services.prompt_expansion_service import PromptExpansionService
2026-07-12 02:54:45 +08:00
from backend.services.prompt_governance_service import (
GenerationFailureClassifier,
GenerationRouteService,
ImageModerationService,
PromptModerationService,
PromptSemanticNormalizer,
PromptTranslationService,
)
from backend.services.quick_character_consistency import (
QUICK_CHARACTER_TARGETS,
append_identity_lock,
build_identity_lock,
consistency_metadata,
explicit_identity_fields_present,
identity_lock_hash,
is_quick_character_node,
quick_character_batch_id,
requested_identity_lock_hash,
safe_route_snapshot,
)
from backend.services.queue_service import QueueService
2026-07-12 02:54:45 +08:00
from backend.services.reference_binding_mapper import ReferenceBindingMapper
from backend.services.workflow_service import (
LOCKED_NODE_STATUSES,
WorkflowService,
is_repeatable_single_image_node,
locked_node_edit_error,
)
from backend.services.workflow_material_snapshot_service import WorkflowMaterialSnapshotService
from core.event_bus import EventBus
from core.generation_errors import provider_failure_attribution, provider_failure_user_message
from core.identity import RequestContext
from engines.character_flow import canonical_gradual_node_key
from engines.image_provider import ImageProviderError
from engines.single_flow import SingleFlowEngine
_NODE_GENERATION_LOCKS_GUARD = threading.Lock()
_NODE_GENERATION_LOCKS: dict[str, "_NodeGenerationLock"] = {}
_QUICK_CHARACTER_WORKFLOW_LOCKS_GUARD = threading.Lock()
_QUICK_CHARACTER_WORKFLOW_LOCKS: dict[str, "_NodeGenerationLock"] = {}
class _NodeGenerationLock:
def __init__(self):
self.lock = threading.RLock()
self.users = 0
class GenerationService:
def __init__(
self,
workflow_service: WorkflowService,
queue_service: QueueService,
image_service: ImageService,
single_flow_engine: SingleFlowEngine | None = None,
2026-07-06 02:01:45 +08:00
model_provider_service: ModelProviderService | None = None,
2026-07-06 02:40:18 +08:00
cost_guard_service: CostGuardService | None = None,
2026-07-06 02:47:37 +08:00
prompt_expansion_service: PromptExpansionService | None = None,
event_bus: EventBus | None = None,
default_model_route: str | None = None,
require_resolved_model_route: bool = False,
material_resolver: MaterialResolver | None = None,
model_assignments: dict[str, Any] | None = None,
2026-07-12 02:54:45 +08:00
prompt_translation_service: PromptTranslationService | None = None,
prompt_semantic_normalizer: PromptSemanticNormalizer | None = None,
prompt_moderation_service: PromptModerationService | None = None,
generation_route_service: GenerationRouteService | None = None,
generation_failure_classifier: GenerationFailureClassifier | None = None,
image_moderation_service: ImageModerationService | None = None,
reference_binding_mapper: ReferenceBindingMapper | None = None,
composition_builder: CompositionBuilder | None = None,
material_snapshot_service: WorkflowMaterialSnapshotService | None = None,
):
self.workflow_service = workflow_service
self.queue_service = queue_service
self.image_service = image_service
self.single_flow_engine = single_flow_engine or SingleFlowEngine()
self.reference_service = GenerationReferenceService(
image_service,
self.single_flow_engine.storage,
material_resolver,
)
2026-07-06 02:01:45 +08:00
self.model_provider_service = model_provider_service
2026-07-06 02:40:18 +08:00
self.cost_guard_service = cost_guard_service
2026-07-06 02:47:37 +08:00
self.prompt_expansion_service = prompt_expansion_service
self.event_bus = event_bus
self.default_model_route = _optional_text(default_model_route)
self.model_assignments = dict(model_assignments or {})
self.require_resolved_model_route = require_resolved_model_route
2026-07-12 02:54:45 +08:00
self.prompt_translation_service = prompt_translation_service
self.prompt_semantic_normalizer = prompt_semantic_normalizer
self.prompt_moderation_service = prompt_moderation_service
self.generation_route_service = generation_route_service
self.generation_failure_classifier = generation_failure_classifier or GenerationFailureClassifier()
self.image_moderation_service = image_moderation_service
self.reference_binding_mapper = reference_binding_mapper or ReferenceBindingMapper()
self.composition_builder = composition_builder or CompositionBuilder()
self.material_resolver = material_resolver
self.material_snapshot_service = material_snapshot_service
def generate_node(self, node_id: str, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]:
lock_entry = _retain_node_generation_lock(node_id)
lock_entry.lock.acquire()
try:
return self._generate_node_locked(node_id, payload, ctx)
finally:
lock_entry.lock.release()
_release_node_generation_lock(node_id, lock_entry)
def prepare_persisted_generation(
self,
node_id: str,
payload: dict[str, Any],
ctx: RequestContext,
*,
planned_count: int,
) -> dict[str, Any]:
"""Plan one detailed-workflow round without calling an image provider.
Prompt expansion, translation/governance, route selection, material
composition and the budget guard are intentionally evaluated once.
The returned value contains plain JSON only and can be persisted on the
round and copied into independent ``count=1`` candidate tasks.
"""
node = self.workflow_service.get_node(node_id)
self.workflow_service.ensure_node_action_allowed(node_id, "generate", node=node)
workflow = self.workflow_service.get_workflow(node.workflow_id).workflow
if workflow.workflow_type != "character_gradual":
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"persisted generation rounds are available only for detailed character workflows",
{"workflow_id": workflow.workflow_id, "workflow_type": workflow.workflow_type},
)
if node.node_type != "generation":
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"persisted generation preparation requires a generation node",
{"node_id": node.node_id, "node_type": node.node_type},
)
if workflow.status not in {"active", "running"}:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"角色工作流尚未确认开启",
{"workflow_id": workflow.workflow_id, "status": workflow.status},
)
count = min(max(int(planned_count), 1), 8)
profile = self.workflow_service.profile_repository.get(workflow.profile_id)
profile_model_route = _optional_text(getattr(profile, "default_model_route", None))
assigned_route = _optional_text(self.model_assignments.get(_assignment_key(node)))
requested_model_route = str(
payload.get("model_route")
or node.model_route
or assigned_route
or profile_model_route
or self.default_model_route
or "image_low"
)
enriched_payload = self._enrich_generation_payload(node.node_id, payload)
prompt_expansion = self._expand_prompt(workflow.profile_id, node, enriched_payload)
governance = self._govern_prompt(
node=node,
payload=enriched_payload,
prompt_expansion=prompt_expansion,
requested_route=requested_model_route,
ctx=ctx,
)
model_route = governance["route_decision"]["selected_route"] if governance else requested_model_route
if governance and governance.get("prompt"):
prompt_expansion = {
**(prompt_expansion or {}),
"prompt": governance["prompt"],
"negative_prompt": governance.get("negative_prompt")
or (prompt_expansion or {}).get("negative_prompt", ""),
"governance": governance,
}
route_resolution = self._resolve_model_route(model_route)
if self.require_resolved_model_route and route_resolution.get("status") != "resolved":
raise ApiError(
ErrorCode.MODEL_CAPABILITY_UNCONFIRMED,
"未找到可用的生图模型路由,请先在模型配置中完成提供商与路由设置",
{"model_route": model_route, "resolution": route_resolution},
)
persisted_route_resolution = safe_route_snapshot(model_route, route_resolution)
reference_mapping = self.reference_binding_mapper.map(
_reference_binding_summary(enriched_payload),
route_resolution,
)
if reference_mapping["text_constraints"]:
base_prompt = (
_optional_text((prompt_expansion or {}).get("prompt"))
or _optional_text(node.prompt)
or ""
)
prompt_expansion = {
**(prompt_expansion or {}),
"prompt": ", ".join([base_prompt, *reference_mapping["text_constraints"]]),
"negative_prompt": _optional_text((prompt_expansion or {}).get("negative_prompt")) or "",
"reference_binding_mapping": reference_mapping,
}
material_snapshot = self._freeze_round_materials(
workflow=workflow,
node=node,
payload=enriched_payload,
)
routed_material_snapshot = _route_aware_reference_snapshot(material_snapshot, route_resolution)
execution_payload = _apply_round_reference_snapshot(enriched_payload, routed_material_snapshot)
execution_payload, ephemeral_reference_count = _strip_ephemeral_image_data_urls(execution_payload)
if ephemeral_reference_count:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"inline image data cannot be persisted in an asynchronous workflow round",
{
"ephemeral_reference_count": ephemeral_reference_count,
"required_action": "upload_or_import_reference_first",
},
)
# Validate every persistent reference while still in the request path;
# workers later materialize the same frozen URIs into provider inputs.
self.reference_service.resolve(workflow.workflow_id, execution_payload)
cost_guard = self._check_cost_budget(
payload,
model_route,
route_resolution,
planned_task_count=count,
planned_image_count=count,
)
provided_reference_snapshot = (
copy.deepcopy(payload.get("reference_snapshot"))
if isinstance(payload.get("reference_snapshot"), dict)
else {}
)
reference_snapshot = {
**provided_reference_snapshot,
**routed_material_snapshot,
"reference_binding_mapping": reference_mapping,
}
reference_snapshot, snapshot_ephemeral_count = _strip_ephemeral_image_data_urls(reference_snapshot)
if snapshot_ephemeral_count:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"inline image data cannot be persisted in a workflow reference snapshot",
{"required_action": "upload_or_import_reference_first"},
)
generation_request = {
**execution_payload,
"count": 1,
"model_route": model_route,
"resolved_model_route": persisted_route_resolution,
"reference_snapshot": reference_snapshot,
"reference_binding_mapping": reference_mapping,
**({"cost_guard": cost_guard} if cost_guard else {}),
**({"prompt_governance": governance} if governance else {}),
**(
{
"prompt_expansion": prompt_expansion,
"expanded_prompt": prompt_expansion["prompt"],
"expanded_negative_prompt": prompt_expansion["negative_prompt"],
}
if prompt_expansion
else {}
),
}
generation_request, request_ephemeral_count = _strip_ephemeral_image_data_urls(generation_request)
if request_ephemeral_count:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"inline image data cannot be persisted in an asynchronous workflow task",
{"required_action": "upload_or_import_reference_first"},
)
prompt_snapshot = {
"positive_prompt": _optional_text(generation_request.get("expanded_prompt"))
or _optional_text(node.prompt),
"negative_prompt": _optional_text(generation_request.get("expanded_negative_prompt"))
or _optional_text(node.negative_prompt),
"model_route": model_route,
"route_resolution": persisted_route_resolution,
**({"governance": _governance_audit_summary(governance)} if governance else {}),
}
return {
"profile_id": workflow.profile_id,
"workflow_id": workflow.workflow_id,
"node_id": node.node_id,
"node_key": node.node_key,
"node_title": node.title,
"branch_name": node.branch_name,
"model_route": model_route,
"route_resolution": persisted_route_resolution,
"prompt_snapshot": prompt_snapshot,
"reference_snapshot": reference_snapshot,
"generation_request": generation_request,
"planned_count": count,
"prepared_by": ctx.actor_id or "system",
}
def enqueue_prepared_generation(
self,
prepared: dict[str, Any],
*,
round_id: str,
round_display_code: str,
candidate_id: str,
candidate_display_code: str,
candidate_index: int,
ctx: RequestContext,
) -> GenerationTask:
"""Persist one independent candidate task from a shared round plan."""
idempotency_key = f"workflow-round:{round_id}:{candidate_id}:v1"
existing = self.queue_service.get_job_by_idempotency_key(idempotency_key)
if existing is not None:
existing_candidate = _optional_text(existing.metadata.get("candidate_id"))
if existing_candidate and existing_candidate != candidate_id:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"candidate task idempotency key belongs to another candidate",
{"candidate_id": candidate_id, "existing_candidate_id": existing_candidate},
)
return existing
request = copy.deepcopy(prepared.get("generation_request") or {})
request["count"] = 1
if request.get("seed") is not None:
try:
request["seed"] = int(request["seed"]) + max(int(candidate_index) - 1, 0)
except (TypeError, ValueError):
request.pop("seed", None)
request["output_scope"] = {
"workflow_id": prepared["workflow_id"],
"branch_name": prepared.get("branch_name") or "main",
"node_key": prepared.get("node_key") or prepared["node_id"],
"round_id": round_id,
"round_display_code": round_display_code,
"candidate_id": candidate_id,
"candidate_display_code": candidate_display_code,
}
timeout_seconds = _round_timeout_seconds(request, prepared.get("route_resolution"))
return self.queue_service.create_task(
{
"profile_id": prepared.get("profile_id"),
"workflow_id": prepared.get("workflow_id"),
"node_id": prepared.get("node_id"),
"task_type": "workflow_round_candidate",
"status": "queued",
"model_route": prepared.get("model_route"),
"idempotency_key": idempotency_key,
"request": request,
"metadata": {
"source": "workflow_round",
"round_id": round_id,
"candidate_id": candidate_id,
"round_display_code": round_display_code,
"candidate_display_code": candidate_display_code,
"candidate_index": int(candidate_index),
"timeout_seconds": timeout_seconds,
"model_route_resolution": prepared.get("route_resolution") or {},
"display": {
"kind": "workflow_round_candidate",
"summary": f"{candidate_display_code} / {prepared.get('node_title') or prepared.get('node_key') or '候选'}",
},
},
},
ctx,
)
def execute_claimed_generation(
self,
task: GenerationTask,
ctx: RequestContext,
) -> dict[str, Any]:
"""Execute an already-claimed round candidate without finalizing its node."""
if task.status != "running" or task.metadata.get("source") != "workflow_round":
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"workflow-round execution requires a claimed running task",
{"task_id": task.task_id, "status": task.status},
)
if not task.node_id or not task.workflow_id:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"workflow-round task is missing workflow ownership",
{"task_id": task.task_id},
)
node = self.workflow_service.get_node(task.node_id)
workflow = self.workflow_service.get_workflow(task.workflow_id).workflow
if workflow.status == "cancelled":
raise ApiError(
ErrorCode.GENERATION_FAILED,
"owning workflow was cancelled",
{"workflow_id": workflow.workflow_id, "task_id": task.task_id},
)
runtime_request = copy.deepcopy(task.request)
persisted_route_snapshot = dict(runtime_request.get("resolved_model_route") or {})
governance = runtime_request.get("prompt_governance")
governance = governance if isinstance(governance, dict) else None
model_route = _optional_text(runtime_request.get("model_route") or task.model_route) or "image_low"
requested_route = model_route
route_resolution = self._resolve_model_route(model_route)
if self.require_resolved_model_route and route_resolution.get("status") != "resolved":
raise ApiError(
ErrorCode.MODEL_CAPABILITY_UNCONFIRMED,
"configured image route is no longer available for this queued candidate",
{"model_route": model_route, "persisted_route": persisted_route_snapshot},
)
_validate_persisted_route_identity(
persisted_route_snapshot,
route_resolution,
model_route=model_route,
)
# Full provider settings and headers live only in this worker's memory.
runtime_request["resolved_model_route"] = route_resolution
reference_images = self.reference_service.resolve(workflow.workflow_id, runtime_request)
runtime_request["count"] = 1
runtime_request["input_images"] = reference_images
runtime_request.pop("image", None)
assets: list[Any] = []
images: list[Any] = []
restricted_images: list[Any] = []
try:
try:
assets = self.single_flow_engine.generate(node, task, runtime_request)
except ImageProviderError as exc:
fallback = self._content_safety_fallback(
exc=exc,
runtime_request=runtime_request,
governance=governance,
requested_route=requested_route,
ctx=ctx,
)
if fallback is None:
raise
runtime_request = fallback["request"]
route_resolution = fallback["route_resolution"]
model_route = fallback["model_route"]
assets = self.single_flow_engine.generate(node, task, runtime_request)
if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx):
self._cleanup_generation_outputs(assets=assets, images=[])
raise RuntimeError("workflow-round task was cancelled")
for asset in assets:
image_payload = {
"profile_id": workflow.profile_id,
"workflow_id": workflow.workflow_id,
"node_id": node.node_id,
"task_id": task.task_id,
"image_uri": asset.image_uri,
"thumbnail_uri": asset.thumbnail_uri,
"positive_prompt": asset.positive_prompt,
"negative_prompt": asset.negative_prompt,
"model_used": route_resolution.get("model_id"),
"model_route": asset.model_route,
"seed": asset.seed,
"width": asset.width,
"height": asset.height,
"is_selected": False,
"metadata": {
**asset.metadata,
"workflow_round": {
"round_id": task.metadata.get("round_id"),
"candidate_id": task.metadata.get("candidate_id"),
"round_display_code": task.metadata.get("round_display_code"),
"candidate_display_code": task.metadata.get("candidate_display_code"),
},
**({"prompt_governance": _governance_audit_summary(governance)} if governance else {}),
"reference_binding_mapping": runtime_request.get("reference_binding_mapping") or {},
},
}
moderation = self._moderate_generated_image(image_payload, governance, model_route)
self._apply_restoration_feedback(moderation)
image_payload["metadata"] = {**image_payload["metadata"], "image_moderation": moderation}
if moderation.get("action") in {"quarantine", "reject", "regenerate"}:
image_payload["metadata"]["quarantined"] = True
image_payload["metadata"]["gallery_visibility"] = "restricted"
created = self.image_service.create_image(image_payload, ctx)
if moderation.get("action") in {"quarantine", "reject", "regenerate"}:
restricted_images.append(created)
else:
images.append(created)
if len(images) != 1:
raise ApiError(
ErrorCode.GENERATION_FAILED,
"candidate provider did not return exactly one usable image",
{
"task_id": task.task_id,
"usable_image_count": len(images),
"restricted_image_count": len(restricted_images),
},
)
except Exception:
self._cleanup_generation_outputs(assets=assets, images=[*images, *restricted_images])
raise
provider_failure = _provider_failure_from_assets([asset.metadata for asset in assets])
result: dict[str, Any] = {
"image_ids": [images[0].image_id],
"round_id": task.metadata.get("round_id"),
"candidate_id": task.metadata.get("candidate_id"),
"model_route": model_route,
"provider_id": route_resolution.get("provider_id"),
"provider_model": route_resolution.get("model_id"),
}
if provider_failure:
result["provider_failure"] = provider_failure
return result
def _freeze_round_materials(
self,
*,
workflow: Any,
node: Any,
payload: dict[str, Any],
) -> dict[str, Any]:
provided = payload.get("reference_snapshot")
provided = copy.deepcopy(provided) if isinstance(provided, dict) else {}
if self.material_snapshot_service is None:
return provided
dependency = payload.get("dependency_context")
dependency = dependency if isinstance(dependency, dict) else {}
bindings = dependency.get("material_bindings")
bindings = bindings if isinstance(bindings, dict) else {}
temporary = payload.get("temporary_references")
temporary = temporary if isinstance(temporary, list) else dependency.get("temporary_references")
temporary = temporary if isinstance(temporary, list) else bindings.get("temporary_references")
temporary = temporary if isinstance(temporary, list) else provided.get("temporary_references")
temporary = temporary if isinstance(temporary, list) else []
navigation = payload.get("navigation_context")
navigation = navigation if isinstance(navigation, dict) else dependency.get("navigation_context")
navigation = navigation if isinstance(navigation, dict) else bindings.get("navigation_context")
navigation = navigation if isinstance(navigation, dict) else {}
return self.material_snapshot_service.freeze(
workflow_id=workflow.workflow_id,
node_id=node.node_id,
branch_name=node.branch_name,
material_bindings=bindings,
temporary_references=temporary,
navigation_context=navigation,
)
def _generate_node_locked(self, node_id: str, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]:
node = self.workflow_service.get_node(node_id)
self.workflow_service.ensure_node_action_allowed(node_id, "generate", node=node)
idempotency_key = _optional_text(payload.get("idempotency_key"))
if idempotency_key:
existing_task = self.queue_service.get_job_by_idempotency_key(idempotency_key)
if existing_task is not None:
if existing_task.node_id != node_id:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"idempotency_key belongs to another node",
{
"idempotency_key": idempotency_key,
"node_id": node_id,
"existing_node_id": existing_task.node_id,
},
)
return self._existing_generation_response(existing_task, node_id)
active_task = self._active_generation_task(node)
if node.status in {"queued", "running"} and active_task is not None:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"generation is already in progress for this node",
{
"node_id": node_id,
"status": node.status,
"last_task_id": active_task.task_id,
"task_status": active_task.status,
},
)
if node.status in LOCKED_NODE_STATUSES and not is_repeatable_single_image_node(node):
raise locked_node_edit_error(node)
workflow = self.workflow_service.get_workflow(node.workflow_id).workflow
if workflow.status == "cancelled":
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"generation cannot start for a cancelled workflow",
{"workflow_id": workflow.workflow_id, "status": workflow.status},
)
if workflow.workflow_type in {"character_fast", "character_gradual"} and workflow.status not in {
"active",
"running",
}:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"角色工作流尚未确认开启",
{
"workflow_id": workflow.workflow_id,
"workflow_type": workflow.workflow_type,
"status": workflow.status,
"allowed_statuses": ["active", "running"],
},
)
profile = self.workflow_service.profile_repository.get(workflow.profile_id)
profile_model_route = _optional_text(getattr(profile, "default_model_route", None))
assigned_route = _optional_text(self.model_assignments.get(_assignment_key(node)))
quick_character = is_quick_character_node(workflow, node)
quick_context: dict[str, Any] | None = None
if quick_character:
# A quick-character batch has one server-owned route. Per-node
# payload/model_route values must not silently split the identity
# pack across different models.
route_candidate = str(
assigned_route
or payload.get("model_route")
or profile_model_route
or self.default_model_route
or "image_low"
)
quick_context = self._prepare_quick_character_context(
workflow=workflow,
profile=profile,
node=node,
payload=payload,
requested_route=route_candidate,
ctx=ctx,
)
requested_model_route = str(quick_context["requested_route"])
workflow = quick_context["workflow"]
else:
requested_model_route = str(
payload.get("model_route")
or node.model_route
or assigned_route
or profile_model_route
or self.default_model_route
or "image_low"
)
2026-07-12 02:54:45 +08:00
enriched_payload = self._enrich_generation_payload(node.node_id, payload)
if quick_context:
quick_request_metadata = consistency_metadata(
batch_id=quick_context["batch_id"],
lock_hash=quick_context["identity_lock_hash"],
identity_lock=quick_context["identity_lock"],
target=node.node_key,
route_snapshot=quick_context["route_snapshot"],
)
enriched_payload = {
**enriched_payload,
**quick_request_metadata,
"metadata": {
**(enriched_payload.get("metadata") if isinstance(enriched_payload.get("metadata"), dict) else {}),
**quick_request_metadata,
},
}
enriched_payload = _inject_identity_lock_into_prompt_payload(
enriched_payload,
quick_context["identity_lock"],
node,
)
self._validate_quick_character_references(
workflow=workflow,
node=node,
payload=enriched_payload,
quick_context=quick_context,
)
2026-07-12 02:54:45 +08:00
prompt_expansion = self._expand_prompt(workflow.profile_id, node, enriched_payload)
governance = self._govern_prompt(
node=node,
payload=enriched_payload,
prompt_expansion=prompt_expansion,
requested_route=requested_model_route,
ctx=ctx,
)
model_route = governance["route_decision"]["selected_route"] if governance else requested_model_route
if governance and governance.get("prompt"):
prompt_expansion = {
**(prompt_expansion or {}),
"prompt": governance["prompt"],
"negative_prompt": governance.get("negative_prompt") or (prompt_expansion or {}).get("negative_prompt", ""),
"governance": governance,
}
if quick_context:
# Direct mode intentionally bypasses LLM rewriting, but it must
# never bypass the immutable server-owned character identity lock.
prompt_expansion = _locked_quick_character_prompt_expansion(
prompt_expansion=prompt_expansion,
payload=enriched_payload,
node=node,
quick_context=quick_context,
)
2026-07-06 02:01:45 +08:00
route_resolution = self._resolve_model_route(model_route)
2026-07-12 02:54:45 +08:00
if governance:
excluded_fallback = _optional_text(governance.get("route_decision", {}).get("fallback_route"))
if excluded_fallback and excluded_fallback != model_route:
route_resolution["excluded_fallback_routes"] = [excluded_fallback]
if self.require_resolved_model_route and route_resolution.get("status") != "resolved":
raise ApiError(
ErrorCode.MODEL_CAPABILITY_UNCONFIRMED,
"未找到可用的生图模型路由,请先在模型配置中完成提供商与路由设置",
{"model_route": model_route, "resolution": route_resolution},
)
quick_metadata: dict[str, Any] = {}
if quick_context:
effective_route_snapshot = {
**safe_route_snapshot(model_route, route_resolution),
"batch_requested_route": requested_model_route,
"safety_fallback_applied": model_route != requested_model_route,
}
quick_metadata = consistency_metadata(
batch_id=quick_context["batch_id"],
lock_hash=quick_context["identity_lock_hash"],
identity_lock=quick_context["identity_lock"],
target=node.node_key,
route_snapshot=effective_route_snapshot,
)
2026-07-12 02:54:45 +08:00
reference_mapping = self.reference_binding_mapper.map(_reference_binding_summary(enriched_payload), route_resolution)
if reference_mapping["text_constraints"]:
base_prompt = _optional_text((prompt_expansion or {}).get("prompt")) or _optional_text(getattr(node, "prompt", None)) or ""
prompt_expansion = {
**(prompt_expansion or {}),
"prompt": ", ".join([base_prompt, *reference_mapping["text_constraints"]]),
"negative_prompt": _optional_text((prompt_expansion or {}).get("negative_prompt")) or "",
"reference_binding_mapping": reference_mapping,
}
2026-07-06 02:40:18 +08:00
cost_guard = self._check_cost_budget(payload, model_route, route_resolution)
reference_images = self.reference_service.resolve(workflow.workflow_id, enriched_payload)
runtime_generation_request = {
2026-07-06 02:01:45 +08:00
**payload,
**quick_metadata,
"metadata": {
**(payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {}),
**quick_metadata,
},
2026-07-06 02:01:45 +08:00
"model_route": model_route,
"resolved_model_route": route_resolution,
2026-07-06 02:40:18 +08:00
**({"cost_guard": cost_guard} if cost_guard else {}),
2026-07-12 02:54:45 +08:00
**({"prompt_governance": governance} if governance else {}),
"reference_binding_mapping": reference_mapping,
2026-07-06 02:47:37 +08:00
**(
{
"prompt_expansion": prompt_expansion,
"expanded_prompt": prompt_expansion["prompt"],
"expanded_negative_prompt": prompt_expansion["negative_prompt"],
}
if prompt_expansion
else {}
),
2026-07-06 02:01:45 +08:00
}
generation_request, ephemeral_reference_count = _strip_ephemeral_image_data_urls(runtime_generation_request)
if ephemeral_reference_count:
generation_request["reference_persistence"] = {
"ephemeral_data_urls_omitted": ephemeral_reference_count,
}
task = self.queue_service.create_task(
{
"profile_id": workflow.profile_id,
"workflow_id": workflow.workflow_id,
"node_id": node_id,
"status": "queued",
2026-07-06 02:01:45 +08:00
"model_route": model_route,
"idempotency_key": idempotency_key,
2026-07-06 02:01:45 +08:00
"request": generation_request,
"metadata": {
"source": "nodes.generate",
**_generation_task_display_metadata(
profile=profile,
workflow=workflow,
node=node,
payload=payload,
),
**quick_metadata,
"model_route_resolution": (
safe_route_snapshot(model_route, route_resolution) if quick_context else route_resolution
),
2026-07-12 02:54:45 +08:00
**({"prompt_governance": _governance_audit_summary(governance)} if governance else {}),
2026-07-06 02:01:45 +08:00
},
},
ctx,
)
self._publish(
"generation.node_queued",
{"workflow_id": workflow.workflow_id, "node_id": node_id, "task_id": task.task_id},
)
queued_metadata = {
**node.metadata,
**quick_metadata,
"last_task_id": task.task_id,
"last_generate_request": generation_request,
}
execution_metadata = queued_metadata.get("execution")
if isinstance(execution_metadata, dict) and execution_metadata.get("prepared_only") is True:
queued_metadata["execution"] = {
**execution_metadata,
"prepared_only": False,
"task_id": task.task_id,
}
queued_node_payload = {
"status": "queued",
"model_route": model_route,
"metadata": queued_metadata,
}
try:
self._queue_generation_node(node, queued_node_payload, ctx)
except Exception:
if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx):
return self._finalize_cancelled_generation(
task_id=task.task_id,
node_id=node_id,
workflow_id=workflow.workflow_id,
assets=[],
images=[],
ctx=ctx,
)
try:
self.queue_service.update_task_if_status(
task.task_id,
{"queued"},
{
"status": "failed",
"progress": 100,
"error_message": "node could not enter the generation queue",
},
ctx,
)
except Exception:
pass
raise
running_task = self.queue_service.update_task_if_status(
task.task_id,
{"queued"},
{"status": "running", "progress": 20},
ctx,
require_workflow_not_cancelled=True,
)
if running_task is None:
current_task = self.queue_service.get_job(task.task_id)
if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx):
return self._finalize_cancelled_generation(
task_id=task.task_id,
node_id=node_id,
workflow_id=workflow.workflow_id,
assets=[],
images=[],
ctx=ctx,
)
raise ApiError(
ErrorCode.GENERATION_FAILED,
"generation task changed before provider execution",
{"task_id": task.task_id, "status": current_task.status},
)
task = running_task
running_node = self.workflow_service.update_node(node_id, {"status": "running"}, ctx)
self._publish(
"generation.node_running",
{"workflow_id": workflow.workflow_id, "node_id": node_id, "task_id": task.task_id},
)
if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx):
return self._finalize_cancelled_generation(
task_id=task.task_id,
node_id=node_id,
workflow_id=workflow.workflow_id,
assets=[],
images=[],
ctx=ctx,
)
assets: list[Any] = []
images: list[Any] = []
2026-07-12 02:54:45 +08:00
restricted_images: list[Any] = []
try:
runtime_generation_request = {
**runtime_generation_request,
"input_images": reference_images,
}
runtime_generation_request.pop("image", None)
2026-07-12 02:54:45 +08:00
try:
assets = self.single_flow_engine.generate(running_node, task, runtime_generation_request)
except ImageProviderError as exc:
fallback = self._content_safety_fallback(
exc=exc,
runtime_request=runtime_generation_request,
governance=governance,
requested_route=requested_model_route,
ctx=ctx,
)
if fallback is None:
raise
runtime_generation_request = fallback["request"]
route_resolution = fallback["route_resolution"]
model_route = fallback["model_route"]
assets = self.single_flow_engine.generate(running_node, task, runtime_generation_request)
if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx):
return self._finalize_cancelled_generation(
task_id=task.task_id,
node_id=node_id,
workflow_id=workflow.workflow_id,
assets=assets,
images=images,
ctx=ctx,
)
2026-07-12 02:54:45 +08:00
precomputed_moderation: dict[str, dict[str, Any]] = {}
if self.image_moderation_service:
for asset in assets:
preview_payload = {
"image_uri": asset.image_uri,
"thumbnail_uri": asset.thumbnail_uri,
"positive_prompt": asset.positive_prompt,
"negative_prompt": asset.negative_prompt,
"model_route": asset.model_route,
}
precomputed_moderation[asset.image_uri] = self._moderate_generated_image(preview_payload, governance, model_route)
if any(item.get("action") == "regenerate" for item in precomputed_moderation.values()) and not runtime_generation_request.get("post_moderation_regeneration"):
self._cleanup_generation_outputs(assets=assets, images=[])
retry_seed = int(runtime_generation_request.get("seed") or 1000) + 1
runtime_generation_request = {**runtime_generation_request, "seed": retry_seed, "post_moderation_regeneration": {"attempted": True, "reason": "image_moderation"}}
assets = self.single_flow_engine.generate(running_node, task, runtime_generation_request)
precomputed_moderation = {}
for asset in assets:
image_quick_metadata = quick_metadata
if quick_context:
image_quick_metadata = consistency_metadata(
batch_id=quick_context["batch_id"],
lock_hash=quick_context["identity_lock_hash"],
identity_lock=quick_context["identity_lock"],
target=node.node_key,
route_snapshot={
**safe_route_snapshot(model_route, route_resolution),
"batch_requested_route": requested_model_route,
"safety_fallback_applied": model_route != requested_model_route,
"provider_fallback_applied": bool(runtime_generation_request.get("route_fallback")),
},
)
2026-07-12 02:54:45 +08:00
image_payload = {
"profile_id": workflow.profile_id,
"workflow_id": workflow.workflow_id,
"node_id": node_id,
"task_id": task.task_id,
"batch_id": quick_context["batch_id"] if quick_context else None,
2026-07-12 02:54:45 +08:00
"image_uri": asset.image_uri,
"thumbnail_uri": asset.thumbnail_uri,
"positive_prompt": asset.positive_prompt,
"negative_prompt": asset.negative_prompt,
"model_route": asset.model_route,
"seed": asset.seed,
"width": asset.width,
"height": asset.height,
# Keep records unselected until the task completion CAS
# wins. A concurrent cancellation can then roll them
# back without disturbing an older selected image.
"is_selected": False,
"metadata": {
**asset.metadata,
**image_quick_metadata,
2026-07-12 02:54:45 +08:00
**({"prompt_governance": _governance_audit_summary(governance)} if governance else {}),
"reference_binding_mapping": runtime_generation_request.get("reference_binding_mapping") or {},
},
}
moderation = precomputed_moderation.get(asset.image_uri) or self._moderate_generated_image(image_payload, governance, model_route)
self._apply_restoration_feedback(moderation)
image_payload["metadata"] = {**image_payload["metadata"], "image_moderation": moderation}
if moderation.get("action") in {"quarantine", "reject", "regenerate"}:
image_payload["metadata"]["quarantined"] = True
image_payload["metadata"]["gallery_visibility"] = "restricted"
created_image = self.image_service.create_image(image_payload, ctx)
if moderation.get("action") in {"quarantine", "reject", "regenerate"}:
restricted_images.append(created_image)
else:
images.append(created_image)
except Exception as exc:
if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx):
return self._finalize_cancelled_generation(
task_id=task.task_id,
node_id=node_id,
workflow_id=workflow.workflow_id,
assets=assets,
images=images,
ctx=ctx,
)
2026-07-12 02:54:45 +08:00
self._cleanup_generation_outputs(assets=assets, images=[*images, *restricted_images])
failure = self._record_generation_failure(
task=task,
node_id=node_id,
workflow_id=workflow.workflow_id,
route_resolution=route_resolution,
exc=exc,
ctx=ctx,
)
if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx):
return self._finalize_cancelled_generation(
task_id=task.task_id,
node_id=node_id,
workflow_id=workflow.workflow_id,
assets=assets,
images=images,
ctx=ctx,
)
if isinstance(exc, ApiError):
raise
raise ApiError(
ErrorCode.GENERATION_FAILED,
provider_failure_user_message(failure),
failure,
) from exc
2026-07-06 02:14:13 +08:00
provider_failure = _provider_failure_from_assets([asset.metadata for asset in assets])
result: dict[str, Any] = {"image_ids": [image.image_id for image in images]}
2026-07-12 02:54:45 +08:00
if restricted_images:
result["restricted_image_ids"] = [image.image_id for image in restricted_images]
result["image_moderation"] = "restricted"
2026-07-06 02:14:13 +08:00
update_payload: dict[str, Any] = {
"status": "succeeded",
"progress": 100,
"result": result,
}
if quick_context:
final_quick_metadata = consistency_metadata(
batch_id=quick_context["batch_id"],
lock_hash=quick_context["identity_lock_hash"],
identity_lock=quick_context["identity_lock"],
target=node.node_key,
route_snapshot={
**safe_route_snapshot(model_route, route_resolution),
"batch_requested_route": requested_model_route,
"safety_fallback_applied": model_route != requested_model_route,
"provider_fallback_applied": bool(runtime_generation_request.get("route_fallback")),
},
)
update_payload["metadata"] = {**task.metadata, **final_quick_metadata}
2026-07-06 02:14:13 +08:00
if provider_failure:
result["provider_failure"] = provider_failure
update_payload["metadata"] = {
**(update_payload.get("metadata") if isinstance(update_payload.get("metadata"), dict) else task.metadata),
"provider_failure": provider_failure,
}
completed_task = self.queue_service.update_task_if_status(
task.task_id,
{"running"},
2026-07-06 02:14:13 +08:00
update_payload,
ctx,
require_workflow_not_cancelled=True,
)
if completed_task is None:
current_task = self.queue_service.get_job(task.task_id)
if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx):
return self._finalize_cancelled_generation(
task_id=task.task_id,
node_id=node_id,
workflow_id=workflow.workflow_id,
assets=assets,
images=images,
ctx=ctx,
)
2026-07-12 02:54:45 +08:00
self._cleanup_generation_outputs(assets=assets, images=[*images, *restricted_images])
raise ApiError(
ErrorCode.GENERATION_FAILED,
"generation task changed before completion",
{"task_id": task.task_id, "status": current_task.status},
)
if images and workflow.workflow_type != "character_gradual":
images[0] = self.image_service.select_image(images[0].image_id, ctx)
completed_node = self.workflow_service.update_node(node_id, {"status": "completed"}, ctx)
self._publish(
"generation.node_completed",
{
"workflow_id": workflow.workflow_id,
"node_id": node_id,
"task_id": completed_task.task_id,
"image_ids": [image.image_id for image in images],
},
)
return {
"task_id": completed_task.task_id,
"task_status": completed_task.status,
"node_status": completed_node.status,
"images": [image.to_dict() for image in images],
2026-07-12 02:54:45 +08:00
**({"restricted_count": len(restricted_images), "image_moderation": "restricted"} if restricted_images else {}),
}
def _existing_generation_response(self, task: GenerationTask, node_id: str) -> dict[str, Any]:
node = self.workflow_service.get_node(node_id)
images = []
for image_id in task.result.get("image_ids", []):
try:
images.append(self.image_service.get_image(str(image_id)).to_dict())
except ApiError as exc:
if exc.error_code != ErrorCode.RESOURCE_NOT_FOUND:
raise
return {
"task_id": task.task_id,
"task_status": task.status,
"node_status": node.status,
"images": images,
"idempotent_replay": True,
}
def _active_generation_task(self, node: Any) -> GenerationTask | None:
metadata = node.metadata if isinstance(node.metadata, dict) else {}
task_id = _optional_text(metadata.get("last_task_id"))
if not task_id:
return None
try:
task = self.queue_service.get_job(task_id)
except ApiError as exc:
if exc.error_code == ErrorCode.RESOURCE_NOT_FOUND:
return None
raise
if task.node_id == node.node_id and task.status in {"queued", "running"}:
return task
return None
2026-07-06 02:01:45 +08:00
def _resolve_model_route(self, route_name: str) -> dict[str, Any]:
if not self.model_provider_service:
return {"route_name": route_name, "status": "unresolved"}
resolved = self.model_provider_service.resolve_route(route_name, modality="image_generation")
if not resolved:
return {"route_name": route_name, "status": "unresolved"}
provider = resolved.get("provider") or {}
return {
"route_name": resolved["route_name"],
"route_id": resolved["route_id"],
"status": "resolved",
"provider_id": resolved["provider_id"],
"provider_type": provider.get("provider_type"),
"model_id": resolved["model_id"],
"modality": resolved["modality"],
"priority": resolved["priority"],
2026-07-12 02:54:45 +08:00
"settings": dict(resolved.get("settings") or {}),
"capabilities": dict(provider.get("capabilities") or {}),
2026-07-06 02:01:45 +08:00
}
def _prepare_quick_character_context(
self,
*,
workflow: Any,
profile: Any,
node: Any,
payload: dict[str, Any],
requested_route: str,
ctx: RequestContext,
) -> dict[str, Any]:
lock_entry = _retain_quick_character_workflow_lock(workflow.workflow_id)
lock_entry.lock.acquire()
try:
current_workflow = self.workflow_service.get_workflow(workflow.workflow_id).workflow
metadata = dict(current_workflow.metadata or {})
managed = metadata.get("quick_character_identity_managed") == "generation_service_v1"
request_metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {}
requested_batch_id = _optional_text(
payload.get("quick_character_batch_id")
or payload.get("batch_id")
or request_metadata.get("quick_character_batch_id")
or request_metadata.get("batch_id")
)
if managed:
identity_lock = metadata.get("identity_lock") if isinstance(metadata.get("identity_lock"), dict) else None
stored_hash = _optional_text(metadata.get("identity_lock_hash"))
if identity_lock is None or not stored_hash or identity_lock_hash(identity_lock) != stored_hash:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character workflow identity lock is invalid",
{"workflow_id": current_workflow.workflow_id},
)
requested_hash = requested_identity_lock_hash(payload)
if requested_hash and requested_hash != stored_hash:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character identity lock cannot be changed after the batch starts",
{
"workflow_id": current_workflow.workflow_id,
"expected_identity_lock_hash": stored_hash,
"requested_identity_lock_hash": requested_hash,
},
)
if explicit_identity_fields_present(payload):
candidate_hash = identity_lock_hash(build_identity_lock(profile, payload))
if candidate_hash != stored_hash:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character identity fields do not match the active batch",
{
"workflow_id": current_workflow.workflow_id,
"expected_identity_lock_hash": stored_hash,
"requested_identity_lock_hash": candidate_hash,
},
)
batch_id = _optional_text(metadata.get("quick_character_batch_id"))
if not batch_id:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character workflow batch id is missing",
{"workflow_id": current_workflow.workflow_id},
)
if requested_batch_id and requested_batch_id != batch_id:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character batch id does not match the active workflow batch",
{
"workflow_id": current_workflow.workflow_id,
"expected_batch_id": batch_id,
"requested_batch_id": requested_batch_id,
},
)
route_snapshot = (
metadata.get("quick_character_route_snapshot")
if isinstance(metadata.get("quick_character_route_snapshot"), dict)
else {}
)
frozen_route = _optional_text(
route_snapshot.get("requested_route") or route_snapshot.get("route_name")
)
if not frozen_route:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character workflow route snapshot is missing",
{"workflow_id": current_workflow.workflow_id},
)
else:
identity_lock = build_identity_lock(profile, payload)
stored_hash = identity_lock_hash(identity_lock)
requested_hash = requested_identity_lock_hash(payload)
if requested_hash and requested_hash != stored_hash:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"provided identity lock hash does not match the normalized character identity",
{
"workflow_id": current_workflow.workflow_id,
"normalized_identity_lock_hash": stored_hash,
"requested_identity_lock_hash": requested_hash,
},
)
batch_id = requested_batch_id or quick_character_batch_id(current_workflow.workflow_id, stored_hash)
frozen_route = requested_route
route_snapshot = safe_route_snapshot(frozen_route, self._resolve_model_route(frozen_route))
workflow_consistency = consistency_metadata(
batch_id=batch_id,
lock_hash=stored_hash,
identity_lock=identity_lock,
target="all",
route_snapshot=route_snapshot,
)
current_workflow = self.workflow_service.update_workflow(
current_workflow.workflow_id,
{
"metadata": {
**metadata,
**workflow_consistency,
"quick_character_identity_managed": "generation_service_v1",
"quick_character_targets": list(QUICK_CHARACTER_TARGETS),
},
},
ctx,
)
return {
"workflow": current_workflow,
"batch_id": batch_id,
"identity_lock": identity_lock,
"identity_lock_hash": stored_hash,
"requested_route": frozen_route,
"route_snapshot": route_snapshot,
}
finally:
lock_entry.lock.release()
_release_quick_character_workflow_lock(workflow.workflow_id, lock_entry)
def _validate_quick_character_references(
self,
*,
workflow: Any,
node: Any,
payload: dict[str, Any],
quick_context: dict[str, Any],
) -> None:
image_ids, raw_explicit_references = _quick_character_reference_inputs(payload)
if node.node_key != "quick_avatar" and raw_explicit_references and not image_ids:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character identity references must use a generation image_id, not a raw image URI",
{
"workflow_id": workflow.workflow_id,
"node_id": node.node_id,
"quick_character_target": node.node_key,
},
)
if not image_ids:
# Backward compatibility: older callers may still generate the
# four targets without an image anchor. New two-stage callers pass
# the avatar image ID and receive strict batch/hash validation.
return
avatar_reference_found = node.node_key == "quick_avatar"
for image_id in image_ids:
image = self.image_service.get_image(image_id)
if image.workflow_id != workflow.workflow_id or image.profile_id != workflow.profile_id:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character reference image belongs to another workflow or profile",
{
"image_id": image_id,
"workflow_id": workflow.workflow_id,
"image_workflow_id": image.workflow_id,
"profile_id": workflow.profile_id,
"image_profile_id": image.profile_id,
},
)
metadata = image.metadata if isinstance(image.metadata, dict) else {}
image_batch_id = _optional_text(image.batch_id or metadata.get("quick_character_batch_id"))
image_lock_hash = _optional_text(metadata.get("identity_lock_hash"))
if image_batch_id or image_lock_hash:
if (
image_batch_id != quick_context["batch_id"]
or image_lock_hash != quick_context["identity_lock_hash"]
):
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character reference image belongs to another identity batch",
{
"image_id": image_id,
"expected_batch_id": quick_context["batch_id"],
"image_batch_id": image_batch_id,
"expected_identity_lock_hash": quick_context["identity_lock_hash"],
"image_identity_lock_hash": image_lock_hash,
},
)
# Untagged legacy images remain usable only inside their original
# workflow/profile, preserving existing installations without a
# data migration while still blocking cross-workflow references.
source_node = self.workflow_service.get_node(str(image.node_id)) if image.node_id else None
if source_node and source_node.node_key == "quick_avatar":
avatar_reference_found = True
if node.node_key != "quick_avatar" and not avatar_reference_found:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"quick-character downstream generation requires the avatar image_id as an identity anchor",
{
"workflow_id": workflow.workflow_id,
"node_id": node.node_id,
"quick_character_target": node.node_key,
"reference_image_ids": image_ids,
},
)
2026-07-06 02:40:18 +08:00
def _check_cost_budget(
self,
payload: dict[str, Any],
model_route: str,
route_resolution: dict[str, Any],
*,
planned_task_count: int = 1,
planned_image_count: int | None = None,
2026-07-06 02:40:18 +08:00
) -> dict[str, Any] | None:
budget = payload.get("cost_budget") if isinstance(payload.get("cost_budget"), dict) else None
if not budget or not self.cost_guard_service:
return None
guard = self.cost_guard_service.check_generation_budget(
provider_id=route_resolution.get("provider_id"),
provider_model=route_resolution.get("model_id") or model_route,
model_route=model_route,
planned_task_count=max(int(planned_task_count), 1),
planned_image_count=(
max(int(planned_image_count), 1)
if planned_image_count is not None
else _planned_image_count(payload.get("count"))
),
2026-07-06 02:40:18 +08:00
planned_total_tokens=int(budget.get("planned_total_tokens") or 0),
max_task_count=budget.get("max_task_count"),
max_image_count=budget.get("max_image_count"),
max_estimated_cost=budget.get("max_estimated_cost"),
days=budget.get("days"),
unit_prices=budget.get("unit_prices") if isinstance(budget.get("unit_prices"), dict) else None,
)
if not guard["allowed"]:
raise ApiError(ErrorCode.VALIDATION_FAILED, "generation budget exceeded", guard)
return guard
def _queue_generation_node(
self,
original_node: Any,
payload: dict[str, Any],
ctx: RequestContext,
) -> Any:
current = self.workflow_service.get_node(original_node.node_id)
if current.status not in LOCKED_NODE_STATUSES:
return self.workflow_service.update_node(current.node_id, payload, ctx)
if not is_repeatable_single_image_node(current):
raise locked_node_edit_error(current)
repeat_payload = dict(payload)
repeat_metadata = repeat_payload.get("metadata") if isinstance(repeat_payload.get("metadata"), dict) else {}
repeat_payload["metadata"] = {
**repeat_metadata,
"repeat_generation": {
"previous_status": current.status,
"previous_selected_image_id": current.selected_image_id,
"task_id": repeat_metadata.get("last_task_id"),
},
}
after = self.workflow_service.workflow_repository.update_node(current.node_id, repeat_payload)
if after is None:
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "node not found", {"node_id": current.node_id})
self.workflow_service.audit_service.record(
ctx=ctx,
action="update_node",
target_type="workflow_node",
target_id=current.node_id,
before_snapshot=current.to_dict(),
after_snapshot=after.to_dict(),
metadata={"source": "generation.repeatable_single_image"},
)
if self.workflow_service.event_bus:
self.workflow_service.event_bus.publish(
"workflow.node_status_changed",
{
"workflow_id": after.workflow_id,
"node_id": after.node_id,
"before_status": current.status,
"after_status": after.status,
},
)
self.workflow_service.event_bus.publish(
"workflow.node_updated",
{"workflow_id": after.workflow_id, "node_id": after.node_id},
)
return after
2026-07-06 02:47:37 +08:00
def _expand_prompt(
self,
profile_id: str,
node,
payload: dict[str, Any],
) -> dict[str, Any] | None:
if not self.prompt_expansion_service:
return None
profile = self.workflow_service.profile_repository.get(profile_id)
if profile is None:
return None
return self.prompt_expansion_service.expand_for_node(profile, node, payload)
2026-07-12 02:54:45 +08:00
def _govern_prompt(
self,
*,
node: Any,
payload: dict[str, Any],
prompt_expansion: dict[str, Any] | None,
requested_route: str,
ctx: RequestContext,
) -> dict[str, Any] | None:
if not any((self.prompt_translation_service, self.prompt_semantic_normalizer, self.prompt_moderation_service, self.generation_route_service)):
return None
original = _optional_text(payload.get("user_prompt") or payload.get("prompt") or payload.get("prompt_patch")) or _optional_text(getattr(node, "prompt", None)) or ""
processing_mode = str(payload.get("prompt_processing_mode") or "auto").strip().lower()
direct_prompt = processing_mode == "direct"
expanded = original if direct_prompt else (_optional_text((prompt_expansion or {}).get("prompt")) or original)
2026-07-12 02:54:45 +08:00
negative = _optional_text((prompt_expansion or {}).get("negative_prompt")) or _optional_text(getattr(node, "negative_prompt", None)) or ""
entrypoint = _entrypoint(payload)
locked_terms = _string_list(payload.get("locked_terms"))
translation = None
translated = expanded
if self.prompt_translation_service and not direct_prompt:
2026-07-12 02:54:45 +08:00
translation_result = self.prompt_translation_service.translate(
expanded,
entrypoint=entrypoint,
user_allowed=bool(payload.get("translation_consent", False)),
model_family=str(payload.get("prompt_model_family") or "natural_language"),
locked_terms=locked_terms,
budget=_positive_int(payload.get("prompt_budget")),
)
translation = translation_result.to_dict()
translated = translation_result.translated_text
normalization = None
final_prompt = translated
if self.prompt_semantic_normalizer and not direct_prompt:
2026-07-12 02:54:45 +08:00
normalization = self.prompt_semantic_normalizer.normalize(translated, locked_terms=locked_terms)
final_prompt = normalization["normalized_text"]
moderation = (
self.prompt_moderation_service.moderate(
original_prompt=original,
translated_prompt=translated,
final_prompt=final_prompt,
negative_prompt=negative,
reference_bindings=_reference_binding_summary(payload),
)
if self.prompt_moderation_service
else None
)
if moderation is None:
from backend.services.prompt_governance_service import PromptModerationDecision
moderation = PromptModerationDecision("safe", 1.0, [], ["moderation_not_configured"], "allow", None, "none", None, "")
if self.generation_route_service:
route = self.generation_route_service.decide(
requested_route,
moderation,
entrypoint=entrypoint,
user_id=ctx.actor_id,
group_id=_optional_text(payload.get("group_id") or payload.get("chat_group_id")),
permission_context=_permission_context(payload),
)
else:
from backend.services.prompt_governance_service import GenerationRouteDecision
route = GenerationRouteDecision(requested_route, moderation.level, requested_route if moderation.allowed else None, "static_route", None, moderation.allowed, moderation.level == "uncertain", "")
if not route.allowed:
if moderation.level in {"terror_prohibited", "violence_prohibited", "prohibited"}:
try:
self.workflow_service.audit_service.record(
ctx=ctx,
action="generation_content_safety_blocked",
target_type="workflow_node",
target_id=str(getattr(node, "node_id", "")),
metadata={
"priority": "high" if moderation.level in {"terror_prohibited", "violence_prohibited"} else "normal",
"entrypoint": entrypoint,
"moderation_level": moderation.level,
"reason_codes": moderation.reason_codes,
"rules_version": moderation.rules_version,
"group_id": _optional_text(payload.get("group_id") or payload.get("chat_group_id")),
},
)
except Exception:
pass
raise ApiError(
ErrorCode.VALIDATION_FAILED,
moderation.warning or ("内容需要确认后才能生成" if route.requires_confirmation else "内容审核未通过,未创建生成任务"),
{
"moderation_level": moderation.level,
"reason_codes": moderation.reason_codes,
"route_reason": route.reason,
"requires_confirmation": route.requires_confirmation,
"warning": moderation.warning,
},
)
return {
"prompt": final_prompt,
"negative_prompt": negative,
"translation": translation,
"normalization": normalization,
"moderation": moderation.to_dict(),
"route_decision": route.to_dict(),
"entrypoint": entrypoint,
}
def _content_safety_fallback(
self,
*,
exc: ImageProviderError,
runtime_request: dict[str, Any],
governance: dict[str, Any] | None,
requested_route: str,
ctx: RequestContext,
) -> dict[str, Any] | None:
failure = self.generation_failure_classifier.classify(exc)
if failure["failure_class"] != "content_safety_rejection" or not self.prompt_moderation_service or not self.generation_route_service:
return None
if (runtime_request.get("route_fallback") or {}).get("attempted"):
return None
prompt = _optional_text(runtime_request.get("expanded_prompt")) or ""
negative = _optional_text(runtime_request.get("expanded_negative_prompt")) or ""
translation = (governance or {}).get("translation")
translation = translation if isinstance(translation, dict) else {}
moderation = self.prompt_moderation_service.moderate(
original_prompt=_optional_text(translation.get("original_text")) or prompt,
translated_prompt=_optional_text(translation.get("translated_text")) or prompt,
final_prompt=prompt,
negative_prompt=negative,
reference_bindings=[],
)
payload = runtime_request
route = self.generation_route_service.decide(
requested_route,
moderation,
entrypoint=_entrypoint(payload),
user_id=ctx.actor_id,
group_id=_optional_text(payload.get("group_id") or payload.get("chat_group_id")),
permission_context=_permission_context(payload),
)
if not route.allowed or moderation.level != "adult_allowed" or not route.selected_route or route.selected_route == runtime_request.get("model_route"):
return None
resolution = self._resolve_model_route(route.selected_route)
if self.require_resolved_model_route and resolution.get("status") != "resolved":
return None
fallback_cost_guard = self._check_cost_budget(runtime_request, route.selected_route, resolution)
fallback_record = {
"attempted": True,
"initial_route": runtime_request.get("model_route"),
"failure_class": failure,
"moderation_recheck": moderation.to_dict(),
"fallback_route": route.selected_route,
"fallback_reason": route.reason,
}
return {
"model_route": route.selected_route,
"route_resolution": resolution,
"request": {
**runtime_request,
"model_route": route.selected_route,
"resolved_model_route": resolution,
"route_fallback": fallback_record,
"allow_provider_fallback": False,
**({"cost_guard": fallback_cost_guard} if fallback_cost_guard else {}),
},
}
def _moderate_generated_image(self, image_payload: dict[str, Any], governance: dict[str, Any] | None, model_route: str) -> dict[str, Any]:
if not self.image_moderation_service:
return {"status": "not_configured", "action": "allow", "version": "none"}
level = _optional_text((governance or {}).get("moderation", {}).get("level")) or "safe"
route_kind = "nsfw" if level == "adult_allowed" else "safe"
return self.image_moderation_service.moderate(image_payload, requested_level=level, route_kind=route_kind)
def _apply_restoration_feedback(self, moderation: dict[str, Any]) -> None:
if self.material_resolver is None or not hasattr(self.material_resolver, "update_material"):
return
scores = moderation.get("material_restoration_scores")
if not isinstance(scores, dict):
return
for material_id, raw_score in scores.items():
try:
score = min(max(float(raw_score), 0.0), 1.0)
material = self.material_resolver.get_material(str(material_id))
if material is None:
continue
old = material.metadata.get("restoration_feedback") if isinstance(material.metadata.get("restoration_feedback"), dict) else {}
count = int(old.get("count") or 0)
average = ((float(old.get("score") or 0.0) * count) + score) / (count + 1)
self.material_resolver.update_material(str(material_id), {"metadata": {**material.metadata, "restoration_feedback": {"score": round(average, 4), "count": count + 1}}})
except Exception:
continue
def _enrich_generation_payload(self, node_id: str, payload: dict[str, Any]) -> dict[str, Any]:
enriched_payload = dict(payload)
if not isinstance(enriched_payload.get("dependency_context"), dict):
enriched_payload["dependency_context"] = NodeDependencyContextService(
self.workflow_service,
self.image_service,
).get_context(node_id)
2026-07-12 02:54:45 +08:00
self._compile_material_bindings(enriched_payload)
return enriched_payload
2026-07-06 02:47:37 +08:00
2026-07-12 02:54:45 +08:00
def _compile_material_bindings(self, payload: dict[str, Any]) -> None:
if self.material_resolver is None:
return
dependency = payload.get("dependency_context") if isinstance(payload.get("dependency_context"), dict) else {}
bindings = dependency.get("material_bindings") if isinstance(dependency.get("material_bindings"), dict) else {}
active = bindings.get("active_bindings") if isinstance(bindings.get("active_bindings"), list) else []
materials: list[dict[str, Any]] = []
for binding in active:
if not isinstance(binding, dict):
continue
material_ref = binding.get("material") if isinstance(binding.get("material"), dict) else {}
material_id = _optional_text(material_ref.get("material_id") or binding.get("material_id"))
material = self.material_resolver.get_material(material_id) if material_id else None
if material is None or str(getattr(material, "recognition_status", "")) != "confirmed":
continue
strength = binding.get("reference_strength") if isinstance(binding.get("reference_strength"), dict) else {}
materials.append({
"material_id": material.material_id,
"category": binding.get("category"),
"prompt": material.prompt or material_ref.get("prompt"),
"negative_prompt": material.negative_prompt,
"image_uri": material.image_uri,
"metadata": material.metadata,
"user_adjustment": 20.0 if binding.get("required") else 0.0,
"visibility_bonus": 10.0 if binding.get("required") else 0.0,
"reference_strength": strength.get("key"),
"restoration_score": (
material.metadata.get("restoration_feedback", {}).get("score")
if isinstance(material.metadata.get("restoration_feedback"), dict)
else None
),
})
if not materials:
return
composition = self.composition_builder.build({
"materials": materials,
"prompt_budget": payload.get("prompt_budget") or 4000,
"max_reference_images": payload.get("max_reference_images") or 8,
"visible_slots": payload.get("visible_slots") or [],
"season": payload.get("season") or "",
"scene": payload.get("scene") or "",
}).to_dict()
dependency["material_bindings"] = {
**bindings,
"composition": composition,
"material_prompts": [composition["prompt"]] if composition.get("prompt") else [],
"prompt_context": composition.get("prompt") or "",
"reference_bindings": composition.get("reference_bindings") or [],
"generation_params": {
**(bindings.get("generation_params") if isinstance(bindings.get("generation_params"), dict) else {}),
"reference_material_ids": [item["material_id"] for item in composition.get("selected_materials") or []],
},
}
payload["dependency_context"] = dependency
def _publish(self, event_type: str, payload: dict[str, Any]) -> None:
if self.event_bus:
self.event_bus.publish(event_type, payload)
def _cancel_generation_if_requested(
self,
task_id: str,
workflow_id: str,
ctx: RequestContext,
) -> bool:
task = self.queue_service.get_job(task_id)
if task.status == "cancelled":
return True
workflow = self.workflow_service.get_workflow(workflow_id).workflow
if workflow.status != "cancelled" or task.status not in {"queued", "running"}:
return False
try:
task = self.queue_service.cancel_job(
task_id,
ctx,
reason="owning workflow was cancelled",
)
except ApiError:
task = self.queue_service.get_job(task_id)
return task.status == "cancelled"
def _finalize_cancelled_generation(
self,
*,
task_id: str,
node_id: str,
workflow_id: str,
assets: list[Any],
images: list[Any],
ctx: RequestContext,
) -> dict[str, Any]:
cleanup = self._cleanup_generation_outputs(assets=assets, images=images)
task = self.queue_service.get_job(task_id)
node = self.workflow_service.get_node(node_id)
node_metadata = node.metadata if isinstance(node.metadata, dict) else {}
node_task_id = _optional_text(node_metadata.get("last_task_id"))
if node_task_id == task_id and node.status in {"queued", "running", "cancelled"}:
cancellation = task.metadata.get("cancellation") if isinstance(task.metadata, dict) else None
cancellation_reason = (
_optional_text(cancellation.get("reason"))
if isinstance(cancellation, dict)
else None
)
node_update: dict[str, Any] = {
"metadata": {
**node_metadata,
"generation_cancellation": {
"task_id": task_id,
"reason": cancellation_reason or "cancelled",
"cleanup": cleanup,
},
},
}
if node.status in {"queued", "running"}:
node_update["status"] = "cancelled"
node = self.workflow_service.update_node(
node_id,
node_update,
ctx,
)
self._publish(
"generation.node_cancelled",
{
"workflow_id": workflow_id,
"node_id": node_id,
"task_id": task_id,
"node_status": node.status,
"cleanup": cleanup,
},
)
return {
"task_id": task.task_id,
"task_status": task.status,
"node_status": node.status,
"images": [],
"cancelled": True,
}
def _cleanup_generation_outputs(self, *, assets: list[Any], images: list[Any]) -> dict[str, Any]:
removed_image_ids: list[str] = []
removed_uris: list[str] = []
errors: list[dict[str, str]] = []
for image in reversed(images):
image_id = _optional_text(getattr(image, "image_id", None))
if not image_id:
continue
try:
removed = self.image_service.image_repository.delete_metadata(image_id)
if removed is not None:
removed_image_ids.append(image_id)
except Exception as exc:
errors.append(
{
"target": image_id,
"error_type": exc.__class__.__name__,
"message": str(exc),
}
)
seen_uris: set[str] = set()
for asset in assets:
for field in ("image_uri", "thumbnail_uri"):
uri = _optional_text(getattr(asset, field, None))
if not uri or uri in seen_uris:
continue
seen_uris.add(uri)
try:
path = self.single_flow_engine.storage.resolve_uri(uri)
if path.exists() and path.is_file():
path.unlink()
removed_uris.append(uri)
except Exception as exc:
errors.append(
{
"target": uri,
"error_type": exc.__class__.__name__,
"message": str(exc),
}
)
return {
"image_records_removed": removed_image_ids,
"files_removed": removed_uris,
"errors": errors,
}
def _record_generation_failure(
self,
*,
task: GenerationTask,
node_id: str,
workflow_id: str,
route_resolution: dict[str, Any],
exc: Exception,
ctx: RequestContext,
) -> dict[str, Any]:
if isinstance(exc, ImageProviderError):
failure = provider_failure_attribution(exc, route_context=route_resolution, fallback_used=False)
else:
failure = {
"source": "generation_pipeline",
"category": "internal_error",
"error_type": exc.__class__.__name__,
"message": "generation pipeline failed",
"retryable": False,
"fallback_used": False,
}
failed_task = None
try:
failed_task = self.queue_service.update_task_if_status(
task.task_id,
{"queued", "running"},
{
"status": "failed",
"progress": 100,
"error_message": provider_failure_user_message(failure),
"metadata": {**task.metadata, "generation_failure": failure},
},
ctx,
)
except Exception:
pass
if failed_task is not None:
try:
node = self.workflow_service.get_node(node_id)
node_metadata = node.metadata if isinstance(node.metadata, dict) else {}
if (
_optional_text(node_metadata.get("last_task_id")) == task.task_id
and node.status in {"queued", "running"}
):
self.workflow_service.update_node(
node_id,
{
"status": "failed",
"metadata": {
**node_metadata,
"generation_failure": failure,
"last_task_id": task.task_id,
},
},
ctx,
)
except Exception:
pass
self._publish(
"generation.node_failed",
{"workflow_id": workflow_id, "node_id": node_id, "task_id": task.task_id, "failure": failure},
)
return failure
def _locked_quick_character_prompt_expansion(
*,
prompt_expansion: dict[str, Any] | None,
payload: dict[str, Any],
node: Any,
quick_context: dict[str, Any],
) -> dict[str, Any]:
base_prompt = (
_optional_text((prompt_expansion or {}).get("prompt"))
or _optional_text(payload.get("prompt_patch"))
or _optional_text(getattr(node, "prompt", None))
or ""
)
return {
**(prompt_expansion or {}),
"prompt": append_identity_lock(base_prompt, quick_context["identity_lock"]),
"negative_prompt": _optional_text((prompt_expansion or {}).get("negative_prompt"))
or _optional_text(getattr(node, "negative_prompt", None))
or "",
"identity_lock_hash": quick_context["identity_lock_hash"],
"quick_character_batch_id": quick_context["batch_id"],
}
def _inject_identity_lock_into_prompt_payload(
payload: dict[str, Any],
identity_lock: dict[str, Any],
node: Any,
) -> dict[str, Any]:
prepared = dict(payload)
for key in ("user_prompt", "prompt", "prompt_patch"):
if _optional_text(prepared.get(key)):
prepared[key] = append_identity_lock(prepared[key], identity_lock)
return prepared
prepared["prompt_patch"] = append_identity_lock(getattr(node, "prompt", None), identity_lock)
return prepared
def _retain_node_generation_lock(node_id: str) -> _NodeGenerationLock:
key = str(node_id)
with _NODE_GENERATION_LOCKS_GUARD:
entry = _NODE_GENERATION_LOCKS.get(key)
if entry is None:
entry = _NodeGenerationLock()
_NODE_GENERATION_LOCKS[key] = entry
entry.users += 1
return entry
def _release_node_generation_lock(node_id: str, entry: _NodeGenerationLock) -> None:
key = str(node_id)
with _NODE_GENERATION_LOCKS_GUARD:
entry.users -= 1
if entry.users == 0 and _NODE_GENERATION_LOCKS.get(key) is entry:
_NODE_GENERATION_LOCKS.pop(key, None)
def _retain_quick_character_workflow_lock(workflow_id: str) -> _NodeGenerationLock:
key = str(workflow_id)
with _QUICK_CHARACTER_WORKFLOW_LOCKS_GUARD:
entry = _QUICK_CHARACTER_WORKFLOW_LOCKS.get(key)
if entry is None:
entry = _NodeGenerationLock()
_QUICK_CHARACTER_WORKFLOW_LOCKS[key] = entry
entry.users += 1
return entry
def _release_quick_character_workflow_lock(workflow_id: str, entry: _NodeGenerationLock) -> None:
key = str(workflow_id)
with _QUICK_CHARACTER_WORKFLOW_LOCKS_GUARD:
entry.users -= 1
if entry.users == 0 and _QUICK_CHARACTER_WORKFLOW_LOCKS.get(key) is entry:
_QUICK_CHARACTER_WORKFLOW_LOCKS.pop(key, None)
def _quick_character_reference_inputs(payload: dict[str, Any]) -> tuple[list[str], list[str]]:
image_ids: list[str] = []
raw_explicit_references: list[str] = []
def append(value: Any, *, explicit: bool = False, force_image_id: bool = False) -> None:
if value is None:
return
if isinstance(value, (list, tuple, set)):
for item in value:
append(item, explicit=explicit, force_image_id=force_image_id)
return
if isinstance(value, dict):
if value.get("image_id"):
append(value.get("image_id"), force_image_id=True)
return
for key in ("image_uri", "uri", "image", "url", "reference"):
if value.get(key):
append(value.get(key), explicit=explicit, force_image_id=False)
return
text = _optional_text(value)
if not text:
return
if force_image_id or not _is_quick_character_reference_uri(text):
if text not in image_ids:
image_ids.append(text)
elif explicit and text not in raw_explicit_references:
raw_explicit_references.append(text)
append(payload.get("input_images"), explicit=True)
append(payload.get("image"), explicit=True)
append(payload.get("selected_draft_image_ids"), force_image_id=True)
append(payload.get("stage_inputs"))
metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {}
append(metadata.get("selected_draft_image_ids"), force_image_id=True)
append(metadata.get("stage_inputs"))
dependency = payload.get("dependency_context") if isinstance(payload.get("dependency_context"), dict) else {}
append(dependency.get("selected_image_ids"), force_image_id=True)
append(dependency.get("selected_draft_image_ids"), force_image_id=True)
append(dependency.get("stage_inputs"))
injection = dependency.get("injection_template") if isinstance(dependency.get("injection_template"), dict) else {}
append(injection.get("selected_draft_image_ids"), force_image_id=True)
append(injection.get("stage_inputs"))
return image_ids, raw_explicit_references
def _is_quick_character_reference_uri(value: str) -> bool:
lowered = value.strip().lower()
return lowered.startswith(("storage://", "http://", "https://", "data:image/"))
def _assignment_key(node: Any) -> str:
node_key = str(getattr(node, "node_key", "") or "").strip()
canonical_key = canonical_gradual_node_key(node_key)
node_type = str(getattr(node, "node_type", "") or "").strip()
mapping = {
"headshot": "portrait_generation",
"upper_body": "halfbody_generation",
"lower_body": "fullbody_generation",
"full_body": "fullbody_generation",
"turnaround": "sheet_generation",
"design_sheet": "sheet_generation",
"quick_avatar": "quick_generation",
"quick_bust": "quick_generation",
"quick_stand": "quick_generation",
"quick_sheet": "quick_generation",
"style_lock": "hires_fix",
"questionnaire": "quick_generation",
"preview": "quick_generation",
}
if canonical_key in mapping:
return mapping[canonical_key]
if node_type == "virtual_single_image":
return "quick_generation"
return "quick_generation" if node_type in {"profile_draft", "profile_preview"} else node_key
def _generation_task_display_metadata(
*,
profile: Any,
workflow: Any,
node: Any,
payload: dict[str, Any],
) -> dict[str, Any]:
"""Persist stable, human-readable queue labels alongside internal IDs."""
request_metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {}
profile_name = _optional_text(request_metadata.get("profile_name")) or _optional_text(
getattr(profile, "name", None)
)
workflow_type = _optional_text(request_metadata.get("workflow_type")) or _optional_text(
getattr(workflow, "workflow_type", None)
)
workflow_name = _optional_text(request_metadata.get("workflow_name")) or _optional_text(
getattr(workflow, "display_name", None)
)
node_key = _optional_text(request_metadata.get("quick_character_target")) or _optional_text(
getattr(node, "node_key", None)
)
node_title = _optional_text(request_metadata.get("node_title")) or _optional_text(
getattr(node, "title", None)
)
task_summary = _optional_text(request_metadata.get("task_summary")) or _generation_task_summary(
workflow_type=workflow_type,
profile_name=profile_name,
node_title=node_title,
)
return {
**({"profile_name": profile_name} if profile_name else {}),
**({"workflow_type": workflow_type} if workflow_type else {}),
**({"workflow_name": workflow_name} if workflow_name else {}),
**({"node_key": node_key} if node_key else {}),
**({"node_title": node_title} if node_title else {}),
**({"task_summary": task_summary} if task_summary else {}),
}
def _generation_task_summary(
*,
workflow_type: str | None,
profile_name: str | None,
node_title: str | None,
) -> str | None:
workflow_labels = {
"single_image": "单图生成",
"character_fast": "快速角色",
"character_gradual": "角色工作流",
"quick_profile": "快速人设",
}
display_node_title = node_title
if workflow_type == "character_fast" and display_node_title and display_node_title.startswith("快速"):
display_node_title = display_node_title.removeprefix("快速")
parts = [
workflow_labels.get(workflow_type or "", workflow_type),
None if workflow_type == "single_image" else profile_name,
display_node_title,
]
normalized = [part for part in parts if part]
return " / ".join(normalized) if normalized else None
def _optional_text(value: Any) -> str | None:
if value is None:
return None
text = str(value).strip()
return text or None
2026-07-06 02:14:13 +08:00
_OMITTED_EPHEMERAL_REFERENCE = object()
def _strip_ephemeral_image_data_urls(value: Any) -> tuple[Any, int]:
"""Remove inline image payloads before writing a generation request to storage."""
if isinstance(value, str):
if value.lstrip().lower().startswith("data:image/"):
return _OMITTED_EPHEMERAL_REFERENCE, 1
return value, 0
if isinstance(value, dict):
cleaned: dict[Any, Any] = {}
omitted = 0
for key, item in value.items():
prepared, item_omitted = _strip_ephemeral_image_data_urls(item)
omitted += item_omitted
if prepared is not _OMITTED_EPHEMERAL_REFERENCE:
cleaned[key] = prepared
return cleaned, omitted
if isinstance(value, (list, tuple)):
cleaned_items: list[Any] = []
omitted = 0
for item in value:
prepared, item_omitted = _strip_ephemeral_image_data_urls(item)
omitted += item_omitted
if prepared is not _OMITTED_EPHEMERAL_REFERENCE:
cleaned_items.append(prepared)
return cleaned_items, omitted
return value, 0
def _apply_round_reference_snapshot(
payload: dict[str, Any],
snapshot: dict[str, Any],
) -> dict[str, Any]:
"""Replace mutable material lookups with the snapshot's frozen URIs."""
result = copy.deepcopy(payload)
existing_images = result.get("input_images")
if isinstance(existing_images, str):
input_images: list[Any] = [existing_images]
elif isinstance(existing_images, (list, tuple)):
input_images = list(existing_images)
elif existing_images is None:
input_images = []
else:
input_images = [existing_images]
for uri in snapshot.get("reference_uris") or []:
text = _optional_text(uri)
if text and text not in input_images:
input_images.append(text)
if input_images:
result["input_images"] = input_images
dependency = result.get("dependency_context")
if isinstance(dependency, dict):
dependency = copy.deepcopy(dependency)
bindings = dependency.get("material_bindings")
if isinstance(bindings, dict):
bindings = copy.deepcopy(bindings)
generation_params = bindings.get("generation_params")
if isinstance(generation_params, dict):
bindings["generation_params"] = {
**generation_params,
"reference_material_ids": [],
}
# Prompts/composition remain frozen in the payload, while runtime
# image resolution no longer rereads a mutable material record.
bindings["selected_material_ids"] = []
bindings["active_bindings"] = []
bindings["round_reference_snapshot"] = {
"snapshot_hash": snapshot.get("snapshot_hash"),
"material_ids": list(snapshot.get("material_ids") or []),
"reference_uris": list(snapshot.get("reference_uris") or []),
}
dependency["material_bindings"] = bindings
result["dependency_context"] = dependency
return result
def _route_aware_reference_snapshot(
snapshot: dict[str, Any],
route_resolution: dict[str, Any],
) -> dict[str, Any]:
"""Select frozen style references according to the resolved adapter.
Ordinary materials and temporary references retain their legacy primary-
image behavior. A verified style set may add up to two representative
images only when the route explicitly supports semantic reference roles;
the adapter's global ``max_reference_images`` cap is then applied to the
final immutable list.
"""
result = copy.deepcopy(snapshot if isinstance(snapshot, dict) else {})
resolution = route_resolution if isinstance(route_resolution, dict) else {}
settings = resolution.get("settings") if isinstance(resolution.get("settings"), dict) else {}
capabilities = (
resolution.get("capabilities")
if isinstance(resolution.get("capabilities"), dict)
else {}
)
supports_roles = _route_capability_bool(
settings,
capabilities,
"supports_reference_roles",
) is True
supports_reference_images = _route_capability_bool(
settings,
capabilities,
"reference_images",
"supports_reference_images",
)
supports_style_multi_reference = supports_roles and supports_reference_images is not False
raw_limit = settings.get("max_reference_images")
if raw_limit is None:
raw_limit = capabilities.get("max_reference_images")
try:
max_references = min(max(int(raw_limit), 0), 16) if raw_limit is not None else 16
except (TypeError, ValueError):
max_references = 16
references: list[str] = []
materials = result.get("materials") if isinstance(result.get("materials"), list) else []
for material in materials:
if not isinstance(material, dict):
continue
primary = _optional_text(material.get("image_uri"))
metadata = material.get("metadata") if isinstance(material.get("metadata"), dict) else {}
is_style_set = isinstance(metadata.get("style_set"), dict)
if is_style_set and supports_style_multi_reference:
candidates = _string_list(material.get("reference_image_uris"))
if primary and primary not in candidates:
candidates.insert(0, primary)
selected = candidates[:3]
else:
selected = [primary] if primary else []
for uri in selected:
if uri and uri not in references:
references.append(uri)
temporary = (
result.get("temporary_references")
if isinstance(result.get("temporary_references"), list)
else []
)
for item in temporary:
if not isinstance(item, dict):
continue
uri = _optional_text(item.get("image_uri"))
if uri and uri not in references:
references.append(uri)
result["reference_uris"] = references[:max_references]
result["reference_route_policy"] = {
"supports_reference_roles": supports_roles,
"supports_reference_images": supports_reference_images,
"style_multi_reference_enabled": supports_style_multi_reference,
"max_reference_images": max_references,
"selected_reference_count": len(result["reference_uris"]),
}
return result
def _route_capability_bool(
settings: dict[str, Any],
capabilities: dict[str, Any],
*keys: str,
) -> bool | None:
for source in (settings, capabilities):
for key in keys:
if key not in source:
continue
value = source.get(key)
if isinstance(value, bool):
return value
if isinstance(value, (int, float)):
return bool(value)
text = str(value or "").strip().casefold()
if text in {"1", "true", "yes", "on", "enabled"}:
return True
if text in {"0", "false", "no", "off", "disabled", ""}:
return False
return None
def _round_timeout_seconds(request: dict[str, Any], route_resolution: Any) -> int:
resolution = route_resolution if isinstance(route_resolution, dict) else {}
settings = resolution.get("settings") if isinstance(resolution.get("settings"), dict) else {}
raw = request.get("timeout_seconds") or settings.get("timeout_seconds") or 180
try:
timeout = int(raw)
except (TypeError, ValueError):
timeout = 180
return min(max(timeout, 10), 3600)
def _validate_persisted_route_identity(
persisted: dict[str, Any],
runtime: dict[str, Any],
*,
model_route: str,
) -> None:
mismatches: dict[str, dict[str, str]] = {}
for field in ("route_id", "provider_id", "model_id", "modality"):
expected = _optional_text(persisted.get(field))
actual = _optional_text(runtime.get(field))
if expected and expected != actual:
mismatches[field] = {"expected": expected, "actual": actual or ""}
if mismatches:
raise ApiError(
ErrorCode.MODEL_CAPABILITY_UNCONFIRMED,
"queued candidate model route changed after the round was prepared",
{"model_route": model_route, "mismatches": mismatches},
)
2026-07-06 02:14:13 +08:00
def _provider_failure_from_assets(metadata_items: list[dict[str, Any]]) -> dict[str, Any] | None:
for metadata in metadata_items:
failure = metadata.get("provider_error")
if isinstance(failure, dict):
return failure
return None
2026-07-06 02:40:18 +08:00
def _planned_image_count(value: Any) -> int:
try:
count = int(value)
except (TypeError, ValueError):
count = 1
return min(max(count, 1), 8)
2026-07-12 02:54:45 +08:00
def _entrypoint(payload: dict[str, Any]) -> str:
value = _optional_text(payload.get("entrypoint") or payload.get("platform") or payload.get("source")) or "web"
lowered = value.lower()
if "qq" in lowered or "onebot" in lowered:
return "qq"
if "telegram" in lowered:
return "telegram"
if "discord" in lowered:
return "discord"
if lowered in {"web", "api"}:
return lowered
return "unknown"
def _permission_context(payload: dict[str, Any]) -> dict[str, Any]:
configured = payload.get("content_permissions") if isinstance(payload.get("content_permissions"), dict) else {}
result = {
**configured,
"adult_user_allowed": bool(configured.get("adult_user_allowed", payload.get("adult_user_allowed", False))),
"quota_allowed": bool(configured.get("quota_allowed", payload.get("quota_allowed", True))),
}
if "adult_group_allowed" in configured or "adult_group_allowed" in payload:
result["adult_group_allowed"] = bool(configured.get("adult_group_allowed", payload.get("adult_group_allowed")))
return result
def _reference_binding_summary(payload: dict[str, Any]) -> list[dict[str, Any]]:
composition = payload.get("composition") if isinstance(payload.get("composition"), dict) else {}
bindings = composition.get("reference_bindings")
if not isinstance(bindings, list):
dependency = payload.get("dependency_context") if isinstance(payload.get("dependency_context"), dict) else {}
material_bindings = dependency.get("material_bindings") if isinstance(dependency.get("material_bindings"), dict) else {}
bindings = material_bindings.get("reference_bindings")
return [dict(item) for item in bindings or [] if isinstance(item, dict)]
def _governance_audit_summary(governance: dict[str, Any]) -> dict[str, Any]:
translation = governance.get("translation") if isinstance(governance.get("translation"), dict) else {}
moderation = governance.get("moderation") if isinstance(governance.get("moderation"), dict) else {}
route = governance.get("route_decision") if isinstance(governance.get("route_decision"), dict) else {}
normalization = governance.get("normalization") if isinstance(governance.get("normalization"), dict) else {}
return {
"translation": {
"status": translation.get("status"),
"model_route": translation.get("model_route"),
"template_version": translation.get("template_version"),
"accepted": translation.get("accepted"),
},
"normalization": {
"changed_terms": normalization.get("changed_terms") or [],
"meaning_preserved": normalization.get("meaning_preserved", True),
"version": normalization.get("version"),
},
"moderation": {
"level": moderation.get("level"),
"confidence": moderation.get("confidence"),
"categories": moderation.get("categories") or [],
"reason_codes": moderation.get("reason_codes") or [],
"rules_version": moderation.get("rules_version"),
},
"route_decision": route,
"entrypoint": governance.get("entrypoint"),
}
def _string_list(value: Any) -> list[str]:
if isinstance(value, str):
values = value.split(",")
elif isinstance(value, (list, tuple, set)):
values = value
else:
return []
return [str(item).strip() for item in values if str(item).strip()]
def _positive_int(value: Any) -> int | None:
try:
number = int(value)
except (TypeError, ValueError):
return None
return number if number > 0 else None