ComfyUI Integration

1. مسئله واقعی: پذیرش در صف، نتیجهٔ تأییدشده نیست

یک سرویس قرار است workflow به نام portrait-v7.api.json را روی ComfyUI اجرا کند. digest ثبت‌شدهٔ workflow برابر wf:7 است، سه node اصلی و VendorMaskNode@2.4 لازم‌اند، مدل‌ها pin شده‌اند و deadline برابر ۱۸۰ ثانیه است. preflight همه‌چیز را سبز نشان می‌دهد، POST /prompt یک prompt_id=P-82 می‌دهد و بعد هم پیام‌های اجرا دیده می‌شوند. با این حال هنوز حق نداریم بگوییم «تصویر با موفقیت تولید شد». یک integration قابل اتکا باید هویت workflow و dependencyها، نتیجهٔ validation، شناسهٔ prompt، وضعیت terminal و خروجی واقعی را به هم bind کند. artifact مالک این درس ComfyUI API Workflow Contract & Execution Evidence Record v1 است.

2. مرز درس و چیزهایی که عمداً پوشش نمی‌دهیم

این درس دربارهٔ زیبایی تصویر، prompt engineering، sampler، checkpoint یا انتخاب مدل نیست؛ workflow از قبل انتخاب شده است. همچنین scheduler و ظرفیت GPU را بازطراحی نمی‌کند و qualification کلی مدل را جایگزین نمی‌کند. AIE-011 هم مالک Blender Headless Automation است. سؤال محدود این درس این است: آیا همین workflow نسخه‌بندی‌شده، با همین node/model dependencyها، در API mode واجد شرایط بود، معتبر submit شد، واقعاً به یک terminal state رسید و خروجی مورد انتظارش جداگانه اعتبارسنجی شد؟

3. API-format workflow را مثل executable contract ببینید

فایلی که در UI خوب کار می‌کند الزاماً همان representation مناسب API نیست. integration باید workflow_ref، digest دقیق JSON، نسخهٔ ComfyUI و dependency manifest را ثبت کند. تغییر byteهای workflow، نسخهٔ custom node یا مدلِ موردنیاز یعنی qualification قبلی نباید بی‌صدا به اجرای جدید منتقل شود. نام فایل برای identity کافی نیست؛ digest و version evidence لازم‌اند. اگر workflow یا dependencyها drift کرده‌اند، تصمیم درست requalification است، نه ادامه دادن با اعتماد به اجرای قبلی.

4. قبل از submit، capability و dependency را preflight کنید

ComfyUI routeهایی برای مشاهدهٔ featureها، node definitionها و مدل‌های موجود دارد؛ integration می‌تواند از /features، /object_info و routeهای مدل برای preflight استفاده کند. هدف این preflight اثبات «وجود و سازگاری حداقلی» است، نه اثبات کیفیت خروجی. required node classها، مدل‌ها، featureهای لازم و نسخهٔ packageهای سفارشی را با contract مقایسه کنید. هر mismatch قطعی باید قبل از POST /prompt به PRECHECK_FAIL برسد تا خطا با queue/execution قاطی نشود.

5. custom node در UI دیده می‌شود؛ پس API-compatible است؟ نه

ComfyUI API mode یعنی یک non-Comfy client workflow را به server می‌فرستد. مستندات رسمی تصریح می‌کنند custom nodeهایی که به ارتباط مستقیم client-server نیاز دارند با API mode سازگار نیستند. بنابراین «نصب است»، «در UI دیده می‌شود» یا حتی «در اجرای دستی کار می‌کند» evidence کافی برای integration نیست. contract باید api_mode_compatibility را جدا ثبت کند و در صورت عدم اثبات، fail closed کند.

6. dependency pinning فقط برای reproducibility نیست؛ برای supply chain هم هست

custom node package بخشی از executable surface است. نسخه، منبع و policy آن را ثبت کنید. استاندارد فعلی ComfyUI Registry استفاده از eval/exec را در custom nodeها منع می‌کند و نصب runtime package از طریق subprocess را نیز مجاز نمی‌داند؛ این‌ها signalهای مهم امنیتی‌اند، اما guarantee کامل اعتماد نیستند. Registry compliance، visibility یا popularity به‌تنهایی qualification تولیدی MAKNOW نیست. integration باید dependency manifest و provenance خودش را نگه دارد.

7. POST /prompt چه چیزی را ثابت می‌کند؟

در self-hosted server، POST /prompt workflow را validate می‌کند و اگر معتبر باشد آن را وارد execution queue می‌کند. پاسخ موفق می‌تواند prompt_id و queue number بدهد؛ validation failure می‌تواند error و node_errors برگرداند. این مرز را صریح نگه دارید: queue acceptance فقط نشان می‌دهد request برای اجرا پذیرفته شده است. اگر node_errors داریم یا prompt معتبر نشده، state باید VALIDATION_FAIL باشد؛ ساختن success از HTTP response ممنوع است.

8. prompt_id شناسهٔ هم‌بستگی است، نه مهر موفقیت

prompt_id کلید اتصال submit، WebSocket، history و خروجی‌هاست. آن را کنار request_id و workflow digest ذخیره کنید تا evidence رشتهٔ واحدی داشته باشد. اما داشتن prompt_id فقط یعنی یک job شناسه گرفته است. ممکن است بعداً execution error، interruption، timeout یا output failure رخ دهد. downstream نباید صرفاً با دریافت prompt_id اجازهٔ مصرف media را بگیرد.

9. WebSocket را درست تفسیر کنید: executed با terminal success یکی نیست

/ws برای status و execution updateهاست. پیام‌هایی مثل execution_start، executing، progress، execution_error، execution_interrupted و execution_success evidence اجرای prompt هستند. نکتهٔ مهم: طبق مستندات، executed لزوماً پایان کل prompt نیست؛ وقتی یک node UI update برمی‌گرداند ارسال می‌شود. بنابراین integration باید terminal-state policy مشخص داشته باشد و برای success کل workflow به evidence مناسب همان prompt تکیه کند، نه مشاهدهٔ یک executed پراکنده.

10. /history/{prompt_id} را با همان prompt bind کنید

history یک سطح مشاهدهٔ مستقل برای prompt مشخص فراهم می‌کند. integration باید بررسی کند history واقعاً به همان prompt_id مربوط است و output metadata مورد انتظار را نشان می‌دهد. اگر WebSocket قطع شد، history می‌تواند برای recovery مفید باشد، اما نباید evidence گمشده را اختراع کند. اگر نه terminal evidence کافی داریم نه history قابل اتکا، state را success نکنید؛ recheck یا failure bounded لازم است.

11. output contract را قبل از اجرا تعریف کنید

پیش از submit مشخص کنید چند artifact، با چه type/role و چه validationی انتظار دارید. بعد از execution success، actual output manifest را با expected contract مقایسه کنید: count، type/locator، digest و metadataهای لازم. وجود «یک فایل» کافی نیست. اگر دو تصویر لازم بوده ولی فقط یکی ثبت شده، یا digest با artifact مورد انتظار نمی‌خواند، MISSING_OUTPUT/failure درست‌تر از VERIFIED_RESULT است.

12. timeout، cancellation و retry را از execution error جدا نگه دارید

deadline باید بخشی از request contract باشد. پایان deadline یعنی TIMEOUT، نه validation error. interruption یا cancel صریح باید CANCELLED بماند. execution error هم state جدا دارد. این تفکیک برای retry policy مهم است: retry فقط وقتی انجام شود که identity و idempotency strategy روشن است و اجرای دوباره خروجی‌های مبهم یا duplicate نسازد. حذف تفاوت stateها debugging و audit را خراب می‌کند.

13. ماشین حالت محدود پیشنهادی MAKNOW

اگر workflow/dependency/capability/API-mode preflight پاس نشود → PRECHECK_FAIL. اگر submit validation رد شود یا node_errors داریم → VALIDATION_FAIL. اگر terminal execution error برسد → EXECUTION_FAIL. interruption/cancel → CANCELLED. deadline → TIMEOUT. اگر execution success داریم اما output contract کامل نیست → MISSING_OUTPUT. فقط وقتی identity و dependencyها bind هستند، validation پاس شده، terminal success به همان prompt تعلق دارد و output manifest جداگانه validate شده است → VERIFIED_RESULT. این state machine طراحی MAKNOW است، نه الزام نام‌گذاری ComfyUI.

14. مثال کاری و ضدنمونه‌ها

Baseline: ComfyUI و workflow digest ثبت شده‌اند، VendorMaskNode@2.4 دقیقاً مطابق manifest است، API-mode compatibility تأیید شده، node/model preflight پاس است، /prompt بدون node error یک prompt_id می‌دهد، WebSocket به execution_success می‌رسد، history همان prompt دو تصویر مورد انتظار را نشان می‌دهد و digestها match هستند؛ نتیجه VERIFIED_RESULT. ضدنمونه ۱: package سفارشی از 2.4 به 2.5 تغییر کرده ولی class name همان است؛ requalification لازم است. ضدنمونه ۲: prompt accepted است اما execution_error می‌آید؛ نتیجه execution failure است. ضدنمونه ۳: execution success است ولی فقط یک خروجی از دو خروجی expected ثبت شده؛ media نباید downstream برود.

15. Transfer و چک‌لیست نهایی

در transfer، همان درخواست محصول را نگه دارید اما VendorMaskNode فقط از طریق client-server interaction کار می‌کند؛ حالا UI visibility نباید success قبلی را منتقل کند و state باید PRECHECK_FAIL شود. در mutation دوم، submit prompt_id می‌دهد ولی execution error رخ می‌دهد؛ تصمیم باید از نو ساخته شود. چک‌لیست نهایی: ComfyUI version ثبت؟ workflow digest bind؟ dependency manifest pin؟ API-mode compatibility روشن؟ required node/model/features preflight؟ submit validation ثبت؟ prompt_id و queue evidence bind؟ terminal state معتبر؟ history همان prompt؟ expected/actual outputs و digestها validate؟ timeout/cancel جدا؟ فقط در صورت عبور همهٔ gateهای لازم، downstream به VERIFIED_RESULT تکیه کند.