چیت‌شیت
پایپ‌لاین ایجنت پژوهش از صفر
Research Agent Pipeline from Scratch
تولید فرضیه‌ها، بازیابی مقالات، اجرای آزمایش‌های داخل ساندباکس، داوری نتایج و انتشار یک گزارش مستند.
فهرست مطالب
حلقه‌ی پژوهش
معماریاجرای آن
دستورها| دستور | کارکرد |
|---|---|
python3 code/main.py | دموی درس‌های 50 تا 53. چاپ JSON |
python main.py | جست‌وجوی درختی درس 05، بودجه‌ی 30 دلار |
docker run --network=none --memory=8g --cpus=2 --pids-limit=256 --read-only | ساندباکس برای یک آزمایش |
run_report.py "<question>" --out out/ --code <dir> | JSON گزارش، ردگیری محاسبات و شواهد |
run_report.py --eval heldout/questions.json | امتیازدهی به مجموعه‌داده‌های نمونه‌ی عمومی |
run_report.py "<question>" --model replay --cassette <file> | برنامه‌ریزی بر اساس پاسخ‌های ضبط‌شده |
run_report.py "<question>" --corpus <dir> --compare <old>/report.json | نوشتن changes.json |
project_test.py research-report-agent --stage <n> --path <dir> | ارزیابی یک مرحله و تمام مراحل قبلی |
فراخوانی‌های حلقه در کد
کار و کد| وظیفه | کد |
|---|---|
| پیکربندی شیب تغییر | GeneratorConfig(n_passes=4, t_min=0.2, t_max=1.1) |
| پیش‌نویس و رتبه‌بندی | queue, logs = generator.run(seed_prompt) |
| ساخت یک بازیاب | build_client(RetrievalConfig(top_k_lexical=5, max_hops=2)) |
| جست‌وجوی مقالات | result = client.search(query) |
| اجرای یک مشخصه (spec) | ExperimentRunner().run(spec) |
| پیمایش یک متغیر تنظیمی (knob) | AblationRunner(runner).sweep(base, "k", [4, 8, 16, 32]) |
| انتخاب متریک | MetricSpec(name="perplexity", direction=LOWER, scale=LOG) |
| داوری اجراها | evaluator.evaluate(1, metric_spec, candidates, baselines) |
مشخصه‌سازی آزمایش در ساندباکس
کدpython
base = ExperimentSpec(
spec_id="demo_base", hypothesis_id=1,
script_path=script, # یک خط json چاپ می‌کند
config={"k": 16, "steps": 4, "sleep_s": 0.0},
seed=7, # ارسال‌شده به‌عنوان config["__seed"]
wall_timeout_s=15.0, # سخت‌گیرانه، توقف اجباری در صورت تجاوز
memory_cap_mb=256, # انعطاف‌پذیر، پایش پیوسته‌ی RSS
metric_keys=["perplexity", "final_loss"],
)
runner = ExperimentRunner()
base_result = runner.run(base) # پایانی: ok، timeout، oom، crash
base_result.to_dict() # متریک‌ها، peak_rss_mb، stderr_tail
ablate(base, "k", [4, 8]) # شناسه‌ی spec_id معادل demo_base_k_4
اجرای ایجنت گزارش
گام‌به‌گام- ایندکسکلاس
BM25Index(documents)پیکره متنی مارک‌داون را در Rust رتبه‌بندی می‌کند. - برنامه‌ریزیتابع
plan_researchسؤال را به حداکثر 4 جنبه تفکیک می‌کند. - گردآوریتابع
gather_snippetsبه‌ازای هر جنبه، 3 قطعه‌متن را همراه با آفست نگه می‌دارد. - نگارشتابع
write_reportجملات را با نشانگرهای[S1]می‌سازد. - تأییدتابع
reviewبه هر جمله امتیاز می‌دهد.apply_verdictsبقیه را حذف می‌کند. - وضعیتتابع
decide_stateوضعیت‌های completed، needs_review یا failed را بازمی‌گرداند. - انتشارتابع
write_outputsفایل‌های report.html، report.json و trace.json را می‌نویسد.
امتیازها و فرمول‌ها
مفهوم‌ها- فاصله‌ی کسینوسی
1 - dot(a, b)روی بردارهای واحد.- امتیاز رتبه
- 0.4 نوآوری + 0.3 جزئی‌نگری + 0.3 آزمون‌پذیری.
- امتیاز نهایی
- 0.5 برای BM25 نرمال‌شده + 0.3 گراف + 0.2 تازگی.
- امتیاز گراف
- 1 برای تطابق واژگانی، 0.6 در یک گام پرش، 0.3 در دو گام پرش.
- امتیاز نود
- نوآوری 0.4 + کیفیت 0.5 + وزن بودجه 0.1.
- میزان بهبود
- نسبت (خط مبنا - نامزد) / قدرمطلق(خط مبنا) در شرایطی که کمتر بودن بهتر است.
- آزمون t جفتی
t_stat = mean / sqrt(variance / n)، درجه‌ی آزادی n - 1 است.- امتیاز گزارش
- 100 ضربدر (0.4 دقت + 0.3 بازخوانی + 0.3 فکت‌ها).
پیش‌فرض‌های حلقه
پیش‌فرض‌ها| تنظیم | پیش‌فرض | نکته |
|---|---|---|
n_passes | 6 | t_min معادل 0.2 تا t_max معادل 1.2 |
novelty_threshold | 0.25 | فاصله‌ی کمتر به معنای تکراری بودن است |
BM25 `k1`, `b` | 1.5 | b معادل 0.75 است |
top_k_lexical | 10 | مقادیر اولیه (seed) برای پیمایش گراف |
max_hops | 2 | مقادیر بالاتر از 2 محدود (clamp) می‌شوند |
wall_timeout_s | 30.0 | memory_cap_mb برابر 512 است |
improvement_threshold | 0.02 | تغییر کوچک‌تر نویز محسوب می‌شود |
significance_threshold | 0.05 | مقدار p-value بزرگ‌تر نویز محسوب می‌شود |
پیش‌فرض‌های ایجنت گزارش
پیش‌فرض‌ها| تنظیم | پیش‌فرض | نکته |
|---|---|---|
--model | rules | همچنین بازپخش یا زنده |
Budget `max_steps` | 50 | BudgetExceeded وضعیت failed ایجاد می‌کند |
Budget `max_tokens` | 20000 | estimate_tokens برابر len / 4 است |
`review` threshold | 0.6 | همپوشانی لازم برای نگه‌داشتن یک جمله |
`citation_precision` threshold | 0.8 | سخت‌گیرانه‌تر از ناقد |
max_facets | 4 | نمای کلی، نحوه، خطرات، زمان |
max_sentences | 3 | به‌ازای هر بخش |
Reference score | 87.5 | شش سؤال عمومی، از 100 |
خرابی‌ها و راه‌حل‌ها
عیبیابیلاگ نشان می‌دهد:
parse:no hypothesis block found- علت
- پاسخ فاقد بلوک نشانه‌گذاری‌شده است
- راه‌حل
- دما را روی 1.2 یا کمتر نگه دارید
در هر بار گذر،
duplicateلاگ می‌شود- علت
- پیش‌نویس‌ها در اکثر اسم‌ها مشترک هستند
- راه‌حل
- پرامپت اولیه را گسترده‌تر کرده و دوباره اجرا کنید
وضعیت
terminalبرابرcrashهمراه با متریک‌ها است- علت
- کد خروج غیر صفر
- راه‌حل
- اسکریپت را اصلاح کنید. اجراهای ناقص failed محسوب می‌شوند
PairingError- علت
- مقادیر seed بین لیست‌ها متفاوت است
- راه‌حل
- هر دو بازو را با مقادیر seed یکسان دوباره اجرا کنید
حکم ارزیابی
noiseهمراه با بهبود زیاد- علت
- کمتر از 2 جفت، بدون p-value
- راه‌حل
- مقادیر seed بیشتری را اجرا کنید
نود با خطای
loss_divergedشکست می‌خورد- علت
- تابع زیان (loss) بالاتر از 4.0
- راه‌حل
- آن branch را رها کنید. بقیه را توسعه دهید
جمله حذف شد: نام‌ها یا اعداد در منبع نیستند
- علت
- نام جابه‌جا شده یا عدد تغییر کرده است
- راه‌حل
- نگارش را استخراجی (extractive) نگه دارید
مقدار
sourceدر برنامهrules-fallbackاست- علت
- JSON نامعتبر مدل یا عدم تطابق کاست (cassette miss)
- راه‌حل
- یادداشت برنامه را بخوانید. کاست را دوباره ضبط کنید
پرسش‌ها
پرسش و پاسخ- چرا شیب دما تغییر می‌کند؟
- پیش‌نویس‌های بعدی از مسیر منحرف می‌شوند. زیر 0.2 مدل پرامپت اولیه را طوطی‌وار تکرار می‌کند.
- چرا گراف استنادی پیمایش می‌شود؟
- مقالاتی را می‌یابد که از واژگانی غیر از واژگان پرسش استفاده می‌کنند.
- چرا فقط دو گام پرش؟
- سه گام پرش نتایج را منفجر کرده و باعث دریفت از موضوع می‌شود.
- چرا زیرفرایند؟
- کد غیرقابل‌اعتماد نباید هماهنگ‌کننده را متوقف کند و کرش دهد.
- چرا هربار فقط یک متغیر تنظیمی؟
- پیمایش‌های فاکتوریل کامل به‌صورت نمایی رشد می‌کنند.
- چرا آزمون جفتی؟
- هر seed یک تفاوت ایجاد می‌کند. کف نویز همان خطای استاندارد آن‌هاست.
- آیا needs_review شکست محسوب می‌شود؟
- خیر. دقیقاً به انسان نشان می‌دهد کجا را بررسی کند.