۲۹ خرداد ۲۵۸۵ · 12 دقیقه مطالعه
بلاگم حالا خودکار توی اینستاگرام پست میذاره. این پایپلاین ایجنتیِ پشتشه.
ماه پیش از فاصلهی بین نوشتن یه پست فنی و رسوندنش به دست کسایی که واقعاً بخوننش خسته شدم. پست وجود داره. مخاطب یه جای دیگهست. پر کردن این فاصله بهصورت دستی یعنی قالببندی دوباره، تغییر اندازه، بازنویسی برای یه رسانهی دیگه، و هیچکس این کار رو مرتب انجام نمیده.
برای همین خودکارش کردم. نتیجه پایپلاینیه که فید RSS من رو میخونه، هر پست رو به یه کاروسل عکس اینستاگرام تبدیل میکنه و طبق یه برنامهی روزانه آپلودش میکنه، بدون اینکه من بهش دست بزنم. بخش جالبش خود خودکارسازی نیست؛ چیزیه که موقع ساختنش، با ایجنتهای هوش مصنوعی بهعنوان همتوسعهدهنده، یاد گرفتم، و چیزهایی که کد ریویوهاشون واقعاً پیدا کرد.
شکل کلی پایپلاین
سیستم یه ورودی میگیره و دو تا خروجی میده. آدرس یه پست بلاگ رو که بهش بدی، یه شورت یوتیوب و یه کاروسل اینستاگرام میسازه.
شورت مسیر سادهتری داره: یه مدل زبانی بزرگ متن روایت ۶۰ ثانیهای رو مینویسه، سرویس تبدیل متن به گفتار Google Cloud صداش رو میسازه، کتابخونهی Pillow اسلایدهای متنی مینیمال رو رندر میکنه، و کتابخونهی MoviePy اونها رو کنار هم میذاره و یه MP4 با نسبت ۹:۱۶ میسازه. هر پست یه ویدیوی عمودی میشه.
کاروسل خروجی جدیدتر و سختتره. قالب کاروسل عکس اینستاگرام از پایه با ویدیو فرق داره: به تراکم اطلاعات پاداش میده، نه به روایت خطی. هشت تا کارت که با کشیدن انگشت ورق میخورن و هر کدوم بهتنهایی سر پا میایستن، با یه متن ۶۰ ثانیهای که بلند خونده میشه یکی نیستن. همین فرق یه طراحی متفاوت رو تحمیل کرد.
پایپلاین با یه ایجنت launchd اجرا میشه، از SQLite بهعنوان دیتابیس چکپوینت استفاده میکنه تا هر مرحله بتونه بعد از کرش ادامه پیدا کنه، و روزی یه پست رو پردازش میکنه. همهی مرحلهها ایدمپوتنتن. اگه یه فراخوانی TTS شکست بخوره، اجرای بعدی دقیقاً از همون نقطه ادامه میده، بدون اینکه متن رو دوباره تولید کنه.
چرا قالب کاروسل مجبورم کرد از نو فکر کنم
حرکت بدیهی برای خودکار کردن اینستاگرام این بود که شورت رو دوباره به شکل یه ریلز خروجی بگیرم. همون محتوا، پلتفرم دیگه.
ولی ریلزی که برای دیده شدن بهینه شده، اساساً محتوای سرگرمیه. پستهای فنی که توی ۶۰ ثانیه فشرده بشن تبدیل به نویز میشن. خوانندهای که میخواد چیزی رو بفهمه، نمیخواد یه گوینده روی فیلمهای آرشیوی سرورها یه خلاصه براش بخونه.
کاروسلهای اینستاگرام جور دیگهای کار میکنن. خواننده با سرعت خودش ورق میزنه. هر کارت میتونه یه دیاگرام، یه جدول مقایسه، یه یافتهی مشخص یا یه آمار تکی رو نشون بده که حسابی به چشم بیاد. این قالب به سلسلهمراتب اطلاعات پاداش میده، نه به ریتم.
همین، طراحی رو به سمت یه سیستم کارت تایپدار برد. دک کاروسل یه واژگان مشخص داره:
CARD_TYPES = {
"cover": "Title and subtitle for the post",
"concept": "One idea explained in plain language",
"comparison": "Side-by-side: A vs B",
"flow": "Process with numbered steps",
"bar": "Horizontal bar visualization from article data",
"stat": "Single number that matters",
"figure": "An image scraped directly from the article",
"takeaway": "The one thing to remember",
}
یه فراخوانی مخصوص LLM برای دک، متن کامل مطلب رو میگیره و یه آرایهی JSON ساختاریافته با ۶ تا ۹ کارت برمیگردونه. هر کارت یه نوع، یه عنوان و فیلدهای محتوایی مخصوص اون نوع داره. کارت takeaway همیشه آخر میاد. مدل آزادانه خلاصه نمیکنه؛ داره محتوا رو از مطلب انتخاب میکنه و توی ظرفهای از پیش تعریفشده جا میده.
این محدودیت از چیزی که به نظر میاد مهمتره.
قانون «هیچ دادهی ساختگی»
راحتترین راه شکست برای یه پایپلاین محتوایی که LLM میگردونه، توهمه. یه کارت نمودار میلهای که عددهای بنچمارک مندرآوردی نشون میده، یه کارت آمار با رقمی که مطلب هیچوقت نیاورده: اینها اعتماد رو سریعتر از پست نذاشتن از بین میبرن.
پایپلاین دو تا قانون سفتوسخت رو اعمال میکنه. کارتهای نمودار میلهای و آمار قبل از رندر با متن مطلب سنجیده میشن. اگه عددی روی کارت باشه ولی توی مطلب اصلی نباشه، کارت بهجای حذف شدن به نوع concept تنزل پیدا میکنه، تا طول دک ثابت بمونه.
def _validate_deck(deck: list[dict], article_text: str) -> list[dict]:
clean = []
for card in deck:
if card["type"] in ("bar", "stat"):
value = str(card.get("value", ""))
if value and value not in article_text:
card["type"] = "concept" # demote, don't drop
if card["type"] == "figure":
idx = card.get("figure_index", -1)
if idx < 0 or idx >= len(available_figures):
continue # drop invalid figure references entirely
clean.append(card)
return clean
کارتهای تصویر از همین اصل پیروی میکنن، ولی سختگیرانهتر: فقط میتونن به تصویرهایی ارجاع بدن که از خود مطلب برداشته شدن. اسکرپر HTML مطلب رو میگیره، همهی تگهای <img> رو پیدا میکنه، هر چیزی رو که شبیه اجزای ظاهری رابط کاربری باشه (آیکونها، اجزای ناوبری، تصویرهای کوچیکتر از یه حداقل ابعاد پیکسلی) کنار میذاره، بقیه رو دانلود میکنه و بهصورت یه لیست شمارهدار به پرامپت دک میده. مدل میتونه به تصویر ۰، تصویر ۱، تصویر ۲ ارجاع بده. نمیتونه یکی از خودش بسازه.
این یه تصمیم معماری معناداره: LLM انتخابکننده و قالببنده، نه تولیدکنندهی محتوا. مطلب مرجع حقیقته.
پشتهی فنی
سرویس OpenRouter همهی فراخوانیهای LLM رو انجام میده. دلیل عملیش انعطاف در مسیریابیه: مرحلههای مختلف پایپلاین از مدلهای مختلف استفاده میکنن. متن روایت یوتیوب (کوتاه، پرضرب، ۶۰ ثانیه) برای سرعت و هزینه از openai/gpt-4o-mini استفاده میکنه. دک کاروسل (استدلال طولانیتر، خروجی JSON ساختاریافته، الزام وفاداری به محتوا) میتونه سراغ یه مدل تواناتر بره، بدون اینکه هیچ زیرساخت دیگهای عوض بشه. یه اندپوینت، یه کلید API، و برای هر تسک مدل رو عوض کن.
response = openrouter_client.chat.completions.create(
model="openai/gpt-4o-mini",
messages=[
{"role": "system", "content": DECK_SYSTEM_PROMPT},
{"role": "user", "content": article_text},
],
response_format={"type": "json_object"},
)
deck = json.loads(response.choices[0].message.content)["cards"]
همین الگو برای همهی فراخوانیهای LLM توی پایپلاین تکرار میشه. API یکپارچهی OpenRouter یعنی انتخاب مدل یه مسئلهی کانفیگه، نه معماری. وقتی مدل جدیدی میاد که خروجی JSON ساختاریافته رو بهتر درمیاره، یه خط عوض میشه.
سرویس Google Cloud TTS روایت یوتیوب رو صداگذاری میکنه. انتخاب صدا به زمینه بستگی داره: پستهای بلاگ خودم با یه صدای نورال مردونه خونده میشن؛ پستهایی که از آدرسهای بیرونی توی صف میان، با یه صدای زنونه. جزئیات کوچیکیه، ولی وقتی هر روز صدا تولید میکنی و خروجیها طی ماهها روی هم جمع میشن، برای یکدستی مهمه.
voice = texttospeech.VoiceSelectionParams(
language_code="en-US",
name=TTS_VOICE_NAME if is_own_post else TTS_VOICE_NAME_FEMALE,
)
response = tts_client.synthesize_speech(
input=texttospeech.SynthesisInput(text=script),
voice=voice,
audio_config=texttospeech.AudioConfig(
audio_encoding=texttospeech.AudioEncoding.MP3
),
)
تبدیل متن به گفتارِ نورال اونقدر خوب شده که یه پایپلاین محتوایی روزانه میتونه بهش تکیه کنه بدون اینکه صداش رباتی باشه. سقف کیفیت برای محتوای فنی روایتشده دیگه صدا نیست؛ متنه.
کتابخونهی Pillow هر کارت کاروسل رو بهصورت یه JPEG با ابعاد ۱۰۸۰ در ۱۳۵۰ رندر میکنه. نه مرورگری در کاره، نه تبدیل HTML به تصویر، نه Chrome بدون رابط گرافیکی. رندر مستقیمه: فونتها رو لود کن، چیدمان متن رو حساب کن، اشکال پایه رو بکش، تصویرها رو بچسبون، فایل رو بنویس. این کار از روشی که بر پایهی اسکرینشاته کد بیشتری میخواد، ولی خروجی قطعی تولید میکنه، هیچ وابستگی بیرونی موقع اجرا نداره و برای هر کارت چند صد میلیثانیه طول میکشه.
رندرکننده بر اساس نوع کارت تصمیم میگیره کدوم تابع رو صدا بزنه:
def render_card(card: dict, out_path: str, figures: list[Path]) -> None:
img = Image.new("RGB", (1080, 1350), color=BACKGROUND)
draw = ImageDraw.Draw(img)
match card["type"]:
case "cover": _render_cover(draw, img, card)
case "concept": _render_concept(draw, img, card)
case "comparison": _render_comparison(draw, img, card)
case "bar": _render_bar(draw, img, card)
case "figure": _render_figure(draw, img, card, figures)
case "takeaway": _render_takeaway(draw, img, card)
case _: _render_concept(draw, img, card)
img.save(out_path, "JPEG", quality=92)
هر رندرکننده یه تابع مستقله. اضافه کردن یه نوع کارت جدید یعنی یه تابع و یه ورودی توی CARD_TYPES. اجزای پایهی برند، فونتها، رنگها و ثابتهای فاصلهگذاری همه توی یه ماژول هستن. اسکیمای کارت رابط پایدار بین لایهی LLM و لایهی بصریه.
کتابخونهی Instagrapi آپلود روی اینستاگرام رو انجام میده. آپلود کاروسل یه لیست از مسیر تصویرها و یه کپشن میگیره. انتخاب موسیقی یه زنجیرهی اولویت داره: اول آهنگهای ترند رو امتحان کن، اگه جستوجوی ترندها شکست خورد برو سراغ یه آهنگ ثابت، اگه هر دو شکست خوردن بدون موسیقی برو. شکست جستوجوی موسیقی نباید جلوی آپلود رو بگیره.
ایجنتها واقعاً چطور ساختنش
اینجا میخوام آهستهتر پیش برم، چون فرایند توسعه به اندازهی خود محصول جالبه.
قابلیت کاروسل با یه گردشکار مبتنی بر سابایجنتها طراحی و پیادهسازی شد. فرایند اینطوریه: یه مشخصات بنویس، یه برنامهی پیادهسازی بنویس که به تسکهای مجزا شکسته شده، بعد هر تسک رو بده دست یه سابایجنت پیادهساز تازه که از تسکهای دیگه خبر نداره، و بلافاصله بعدش یه سابایجنت بازبین مستقل که فقط پیادهسازی رو میبینه و هیچ اطلاعی از نیت من نداره.
بازبین برای پرداخت نهایی نیست. بازبین نقش طرف مقابل رو بازی میکنه: کارش پیدا کردن مشکله، نه بهتر کردن سبک.
هفت تا تسک از این حلقه رد شدن. ریویوها قبل از اینکه حتی یه خط کد اجرا بشه پنج تا باگ واقعی پیدا کردن:
همپوشانی زیرعنوان روی کاور. رندرکنندهی کارت کاور زیرعنوان رو با یه فاصلهی عمودی ثابت از عنوان میذاشت. عنوانهای بلند وارد ناحیهی زیرعنوان میشدن و متنها روی هم میافتادن. بازبین این رو گزارش کرد. راهحل این بود که ارتفاع کادر دور عنوان اندازه گرفته بشه و موقعیت عمودی زیرعنوان بهصورت پویا از روی اون به دست بیاد.
خطای IndexError برای لیست خالی. رندرکنندهی کارت flow روی بولتهای مرحلهها حلقه میزد و فرض میکرد حداقل یکیش وجود داره. بازبین توی ذهنش دنبال کرد که اگه LLM دک یه کارت flow با لیست مرحلههای خالی تولید کنه چی میشه، و مسیر کرش رو گزارش کرد. یه گارد اضافه شد.
تست توخالی. تست رندرکنندهی کارت تصویر فقط چک میکرد که تابع بدون استثنا اجرا بشه، ولی هیچ چیزی دربارهی خروجی رو بررسی نمیکرد. بازبین گفت این تست به دلایل اشتباه پاس میشه. بررسیهایی روی وجود فایل JPEG و حجمش اضافه شد.
تداخل کلید مرحله. پایپلاین هر مرحله رو با یه کلید رشتهای توی SQLite چکپوینت میکنه. مرحلهی کاروسل کلید "instagram" رو از کد قدیمی ریلز به ارث برده بود. بازبین متوجه شد که اگه یه روز هر دو مسیر روی یه پست اجرا بشن، یه ردیف چکپوینت مشترک خواهند داشت و پایپلاین یکیشون رو انجامشده حساب میکنه. کلید به "carousel" تغییر کرد.
گرفتن مطلب بدون محافظ در مرحلهی آخر. مرحلهی یکپارچهسازی برای ساختن کاروسل، HTML مطلب رو میگرفت. اگه این درخواست استثنا پرتاب میکرد، استثنا بالا میرفت و پست رو error علامت میزد. وضعیت error پست رو برای تلاشهای بعدی قفل میکنه. تا اون نقطه از زنجیره، آپلود یوتیوب قبلاً موفق شده بود. بازبین این رو گرفت: یه خطای گذرای شبکه موقع گرفتن مطلب باعث میشد پست برای همیشه از صف بیفته، با اینکه ویدیو قبلاً روی یوتیوب رفته بود. حالا یه try/except مرحلهی کاروسل رو از نتیجهی یوتیوب جدا میکنه.
هیچکدوم از این باگها با اجرای کد روی ورودیهای بیدردسر پیدا نمیشد. از اون چیزهاییان که شش هفته بعد از رفتن به پروداکشن پیداشون میکنی، معمولاً یه ساعت بد.
الگویی که ارزش تعمیم داره: بازبینی که از نیت تو خبر نداره و تنها کارش پیدا کردن مشکله، با هر کد ریویویی که توش بازبین از قبل با نویسنده زمینهی مشترک داره فرق میکنه. زمینهی مشترک دقیقاً همون دلیلیه که کد ریویو باگهایی رو که از دست میده، از دست میده.
اجرای روزانهی این سیستم چی یادت میده
خطاهای گذرا بدون یه دروازهی صریح برای تلاش دوباره، دائمی میشن. سرویس Google TTS هر از گاهی ۵۰۴ برمیگردونه. وقتی ردیف مرحلهی یه پست error علامت میخوره، چک «این رو قبلاً دیدم؟» پایپلاین هر ردیف موجودی رو دیدهشده حساب میکنه و برای همیشه از اون پست میگذره. یه اختلال گذرای شبکه یه جای پست رو میسوزونه. راهحل یه دستور تلاش دوبارهی دستیه که ردیف خطا رو پاک میکنه؛ ایدمپوتنت بودن حلقهی اصلی به همین ثابت بستگی داره و نمیخوای ضعیفش کنی.
دیتابیس چکپوینت SQLite برای یه پایپلاین تکنفره که بدون نظارت اجرا میشه انتخاب درستیه. هر مرحله خروجیش رو مینویسه و قبل از شروع مرحلهی بعد خودش رو کاملشده علامت میزنه. پایپلاین رو میشه هر لحظه کشت و از همون جایی که متوقف شده ادامه داد، بدون اینکه کاری که قبلاً موفق شده دوباره اجرا بشه. برای یه کرون روزانه که هیچکس تماشاش نمیکنه، این از چیزی که به نظر میاد مهمتره.
ارزش مسیریابی مدل در OpenRouter به مرور زمان معلوم میشه. متن روایت و دک کاروسل میتونن از مدلهای کاملاً متفاوتی استفاده کنن، بدون هیچ تغییر ساختاری توی کدبیس. وقتی مدلی میاد که خروجی ساختاریافته با کانتکست بلند رو بهتر درمیاره، یه کلید کانفیگ عوض میشه. این انعطاف انگیزهی اولیهی استفاده از OpenRouter نبود؛ فقط وقتی معلوم شد که پایپلاین اونقدر اجرا شده بود که دلم خواست برای تسکهای مختلف مدلهای مختلف رو امتحان کنم.
چی از این ماجرا برداریم
پایپلاینی که توصیف کردم مخصوص سیستم خودمه. چیزی که به جاهای دیگه منتقل میشه نگرش طراحیشه.
مدلهای زبانی بزرگ انتخابکننده و قالببندن، نه تولیدکنندهی محتوا. متن مطلب مرجع حقیقته؛ مدل تصمیم میگیره چی رو بالا بیاره و چطور ساختارش بده. اعتبارسنجی چک میکنه که مدل از مرزی که منبع تعیین کرده بیرون نزده باشه. این کار خروجی رو جوری قابل اعتماد میکنه که تولید محض نمیکنه، و شکستها رو قابل تشخیص میکنه، چون ورودی همیشه قابل ردیابیه.
واژگان کارت تایپدار تصمیمهای محتوایی رو از تصمیمهای رندر جدا میکنه. وقتی یه نوع comparison تعریف کردی، میتونی بدون دست زدن به فراخوانی LLM اون رو برای اینستاگرام، لینکدین یا ایمیل جور دیگهای رندر کنی. اسکیمای کارت رابط پایدار بین لایهی هوشمند و لایهی بصری میشه، و همین جداسازیه که بهت اجازه میده هر طرف رو مستقل تکامل بدی.
الگوی بازبین مستقل در توسعهی ایجنتی دستهای از باگها رو میگیره که مجموعهی تستها از دست میدن: اثرهای متقابل بین بخشهایی که جدا از هم پیادهسازی شدن، گاردهای جاافتاده روی مسیرهای ورودی بدخواهانه، تستهایی که پاس میشن ولی هیچ چیز معناداری رو بررسی نمیکنن. بازبینی که هیچ اطلاعی از نیت تو نداره، مشکلاتی پیدا میکنه که با مشکلات پیداشده توسط بازبینی که از قبل میدونه میخواستی چیکار کنی فرق دارن.
اگه داری چیزی شبیه این طراحی میکنی، معماریای که جواب داده اینهاست: SQLite برای چکپوینتگذاری ایدمپوتنت، OpenRouter برای مسیریابی منعطف مدل به ازای هر تسک، یه اسکیمای خروجی تایپدار که محتوا رو از رندر جدا میکنه، و یه لایهی اعتبارسنجی که حاضر نیست دادهای رو که توی منبع نبوده جلو بفرسته. سرویسهای مشخص قابل جایگزینیان. اصول طراحی نه.
کد منبع پایپلاین عمومی نیست، ولی معماری، پشتهی فنی و فرایند توسعهای که اینجا توصیف شد واقعیان و هر روز دارن اجرا میشن.