تصور کنید تمام یادداشت‌های پراکنده و سریع شما در حین کدنویسی، بدون هیچ تلاش اضافه‌ای به یک راهنمای فنی تمیز و حرفه‌ای تبدیل شوند. اگر هنوز ساعت‌ها وقت خود را صرف بازنویسی دستی فایل‌های README یا ویکی‌های داخلی می‌کنید، این اتوماسیون می‌تواند نقش شما را از یک نویسنده به یک ویراستار تغییر دهد.
یک اسکریپت پایتون ساده اکنون می‌تواند با استفاده از مدل Llama 3.3 70B که روی پلتفرم Oxlo.ai میزبانی شده است، یادداشت‌های تکه‌تکه شده را به راهنماهای فنی صیقل‌خورده تبدیل کند. این سازوکار با پیاده‌سازی یک پرامپت سیستمی سخت‌گیرانه و یک خط لوله بازبینی چندمرحله‌ای، خستگی بازنویسی دستی را حذف می‌کند.
مستندات فنی اغلب از شکافی میان قصد مهندسی و خوانایی برای کاربر رنج می‌برند. با تکیه بر پوشش قبلی ما در مورد نحوه مدیریت حریم خصوصی داده‌ها از طریق حذف اطلاعات شناسایی شخصی (PII) توسط AWS Comprehend و EdgeChains، این گردش‌کار بر یکپارچگی ساختاری و شفافیت خروجی نهایی تمرکز دارد. برای بسیاری از توسعه‌دهندگان، نوشتن مستندات شبیه به یک کار اجباری است که تمرکز آن‌ها را از ارسال کد (Shipping) می‌گیرد.
زمینه و پیاده‌سازی
برای ساخت این ابزار CLI به پایتون ۳.۱۰ یا جدیدتر و یک کلید API از پورتال Oxlo.ai نیاز دارید. این تنظیمات نیازمند SDK شرکت OpenAI است که از طریق دستور pip install openai قابل نصب است. اسکریپت اصلی که tech_writer.py نام دارد، کلاینت را با استفاده از URL پایه https://api.oxlo.ai/v1 مقداردهی می‌کند.
طبق مستندات این راهنما، سیستم بر پایه یک زنجیره اجرایی سه‌مرحله‌ای عمل می‌کند. ابتدا، کلاینت Oxlo.ai یادداشت‌های خام را به مدل زبانی بزرگ (LLM) ارسال می‌کند. در این مرحله، پرامپت سیستمی هرگونه «زبان تبلیغاتی» را ممنوع کرده و ساختاری مشخص شامل عنوان، پیش‌نیازها، مراحل شماره‌دار و بخش‌های عیب‌یابی را تحمیل می‌کند. این پرامپت به‌طور خاص استفاده از بلوک‌های کد برای دستورات، مسیرهای فایل (File Paths) و نمونه‌های پیکربندی را الزامی می‌سازد.
در مرحله دوم، ابزار یک حلقهٔ بازبینی خودکار را اجرا می‌کند. در این گام، مدل در نقش یک «بازبین سخت‌گیر مستندات» قرار می‌گیرد تا گام‌های فراموش‌شده یا ابهامات را شناسایی کند. این فرآیند توسط تابعی مجزا به نام critique_and_revise مدیریت می‌شود که برای دستیابی به دقت بالاتر، با دمای (Temperature) پایین ۰.۲ اجرا می‌گردد.
در نهایت، یک مرحله اصلاحیه، این نقدها را در یک سند Markdown نهایی ادغام می‌کند. این اسکریپت از کتابخانه argparse برای رابط خط فرمان استفاده می‌کند تا کاربران بتوانند یادداشت‌ها را از یک فایل متنی به صورت Pipe ارسال کرده و فایل خروجی را با استفاده از پرچم -o مشخص کنند.
جزئیات فنی
- انتخاب مدل: مدل Llama 3.3 70B به این دلیل انتخاب شده است که دستورات طولانی سیستمی را به‌طور قابل‌اعتمادی دنبال می‌کند و Markdown تمیزی را بدون حاشیه‌های متنی اضافی (Meta-commentary fluff) تولید می‌کند.
- پنجرهٔ زمینه: برای دفترچه‌های راهنمایی (Runbooks) که حجم آن‌ها از ده‌ها هزار توکن فراتر می‌رود، می‌توان مدل را به Kimi K2.6 تغییر داد که یک پنجرهٔ زمینه ۱۳۱ هزار توکنی را مدیریت می‌کند.
- زیرساخت: پایتون ۳.۱۰+ و SDK شرکت OpenAI.
- مدل هزینه: قیمت‌گذاری ثابت به ازای هر درخواست در Oxlo.ai باعث می‌شود هزینه‌ها پیش‌بینی‌پذیر باشد، حتی با وجود اینکه حلقهٔ بازبینی و اصلاح، دو درخواست اضافی به ازای هر سند ایجاد می‌کند. این رویکرد در ادامه مدل قیمت‌گذاری به‌ازای هر درخواست Oxlo.ai است که برای کاهش هزینه‌های عملیاتی در گردش‌کارهای رسانه‌ای و فنی معرفی شد.
مثال کاربردی
برای نمایش این قابلیت، یک کاربر می‌تواند فایلی به نام notes.txt ایجاد کند و موارد زیر را در آن بنویسد:
- استقرار یک سرویس احراز هویت (Auth Service) با استفاده از Redis برای مدیریت نشست‌ها (Sessions).
- متغیرهای محیطی:
AUTH_SECRETوREDIS_URL. - کانتکست بیلد داکر (Docker build context) در مسیر
./authروی پورت ۸۰۸۰. - یک بررسی سلامت (Health check) در مسیر
/healthو محدودیت حافظه ۵۱۲ مگابایت.
اجرای دستور python tech_writer.py notes.txt -o auth_deploy.md این گلوله‌های متنی را به یک راهنمای حرفه‌ای تبدیل می‌کند که دستور docker run را به‌طور صریح با پرچم --memory="512mb" شامل شده و گام‌های مفصل عیب‌یابی در مورد قابلیت دسترسی به REDIS_URL را ارائه می‌دهد.
این رویکرد باعث می‌شود نقش مهندس از یک نویسنده به یک ویراستار تغییر کند. با اتوماسیون دو پیش‌نویس اول، انسان تنها نیاز دارد منطق نهایی را تأیید کند، به جای اینکه از ابتدا با فرمت‌بندی و عبارت‌پردازی بجنگد.
برای تیم‌هایی که سوابق تصمیمات معماری (ADR) در مقیاس بزرگ را مدیریت می‌کنند، قابلیت تغییر مدل بر اساس طول متن بدون تغییر در رده قیمتی، یک مزیت عملیاتی قابل توجه است. این امر «اضطراب توکن» را که معمولاً با سنتز متون فنی طولانی همراه است، از بین می‌برد و به این ترتیب مشکل پیش‌بینی‌ناپذیری هزینه‌های متون طولانی را که پیش‌تر بررسی کرده بودیم، به‌طور کامل حل می‌کند.
شما می‌توانید این ابزار CLI را گسترش دهید تا خروجی نهایی Markdown را به فراخوانی‌های اضافی برای تولید خودکار مشخصات OpenAPI یا طرح‌واره‌های (Schemas) JSON تبدیل کند. این کار کل چرخه مستندسازی API را از یک مجموعه یادداشت خام ساده می‌کند.
گام بعدی شما
- اگر از Llama 3.3 استفاده می‌کنید، یک پرامپت سیستمی برای «نقش بازبین سخت‌گیر» طراحی کنید تا کیفیت خروجی‌هایتان را بسنجید.
- ابزار
tech_writer.pyرا برای تبدیل یادداشت‌های روزانه به مستندات پروژه تست کنید. - برای متون بسیار طولانی، مدل Kimi K2.6 را جایگزین کنید تا از قطع شدن متن جلوگیری شود.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو