أنشئ وكيلًا لتلخيص المراقبة يعمل وفق جدول زمني: دليل المكونات الأربعة واختيار الواجهات

ملاحظة الكاتب: نفكك المكونات الأربعة لوكيل يراقب المصادر ويولّد ملخصات وفق جدول زمني، ونشرح كيف يمكن فصل طبقة استدعاء النموذج عن حزمة SDK محددة باستخدام واجهة متوافقة مع OpenAI، مع مثال Python قابل للتشغيل.

نشرت OpenRouter مؤخرًا درسًا استخدمت فيه @openrouter/agent 0.11.0 لبناء وكيل ذكاء اصطناعي دائم التشغيل بلغة TypeScript، يراقب Hacker News تلقائيًا ويولّد ملخصات وفق جدول زمني. ويلبي هذا السيناريو احتياجًا شائعًا لدى فرق كثيرة: تلخيص أخبار القطاع أو تحركات المنافسين أو المنشورات الرائجة في المجتمعات التقنية كل صباح. ننطلق من هذا المثال لنشرح بنية عامة لوكيل مراقبة وتلخيص لا يرتبط بحزمة SDK محددة.

هذا المقال ليس إعادة سرد لذلك الدرس. لم ينشر الدرس الأصلي سوى معلومات موجزة، لذلك لن نخمن تفاصيل تنفيذه. نركز هنا على سؤال أعم: ما المكونات التي يتألف منها وكيل المراقبة والتلخيص، وكيف نصمم طبقة استدعاء النموذج بحيث يمكن تبديل النماذج ومزودي الخدمة في أي وقت؟

ما ستتعلمه: بنهاية المقال، ستفهم البنية المكونة من أربع مراحل: «التشغيل المجدول، وجلب البيانات، والتلخيص بالنموذج، وإخراج النتائج». وستحصل أيضًا على تطبيق Python يستند إلى واجهة متوافقة مع OpenAI، ويمكن تعديله مباشرة ليناسب احتياجاتك.

أبرز النقاط حول وكيل تلخيص المحتوى المُراقَب

يلخص الجدول التالي استنتاجات المقال، وتتناول الأقسام اللاحقة كل نقطة بالتفصيل.

المكونات الأربعة لوكيل المراقبة والتلخيص

«الوكيل الدائم» هو في الأساس مسار عمل يوقظه مؤقّت على فترات متكررة. لا يحتاج إلى استدلال معقد متعدد الخطوات، لكنه يتطلب مستوى عاليًا من الموثوقية، لأنه يعمل دون مراقبة مستمرة. وتقسيمه إلى أربعة مكونات ذات مسؤوليات واضحة هو أساس تشغيله باستقرار على المدى الطويل.

تتفاعل هذه الأجزاء الأربعة عبر هياكل بيانات بسيطة فقط: يخرج جالب البيانات «قائمة عناصر»، ويخرج الملخّص «نص الملخص»، ويتولى مكوّن الإخراج استلام النص. وميزة هذا التصميم هي إمكانية تشخيص كل مرحلة على حدة؛ فإذا كانت جودة الملخص ضعيفة، نضبط الملخّص وحده، وإذا فشل الإرسال، نفحص مكوّن الإخراج فقط.

في النسخة الأولى، يضع كثيرون كل المنطق في نص برمجي واحد. قد ينجح ذلك، لكنه يصعّب الصيانة. فبمجرد الرغبة في استبدال Hacker News بـ GitHub Trending، أو استخدام نموذج من مزوّد آخر، يصبح تعديل جزء كبير من الشفرة ضروريًا. أما بعد تقسيم النظام إلى مكونات، فلا تتطلب إضافة مصدر معلومات سوى إضافة جالب جديد، بينما يكفي تغيير الإعدادات لتبديل طبقة النموذج.

اختيار طريقة التشغيل المجدول لوكيل تلخيص المراقبة

التشغيل المجدول هو ما يجعل الوكيل يعمل باستمرار. يطبّقه دليل OpenRouter باستخدام عملية دائمة، لكن لديك خيارات متعددة عند النشر الفعلي، ويتوقف الاختيار على البنية التحتية المتاحة لديك.

بالنسبة إلى مهام التلخيص التي تعمل مرة كل ساعة أو يوم، فإن استخدام cron على النظام مع برنامج نصي يخرج فور انتهاء المهمة هو غالبًا الخيار الأكثر جدوى. فهو يتجنب بطبيعته مشكلة تزايد استهلاك الذاكرة في العمليات الدائمة، ويُشغّل المهمة مجددًا في الموعد التالي إذا فشلت. ولا تستحق العملية الدائمة عناء إعدادها إلا إذا كنت تحتاج إلى مراقبة متكررة كل بضع دقائق، أو إلى مشاركة موارد كبيرة بين مرات التشغيل.

كيفية فصل طبقة استدعاء النموذج في وكيل ملخصات المراقبة

هذا هو محور المقال. يستخدم دليل OpenRouter حزمة SDK الخاصة بها، وهي @openrouter/agent، ما يسهّل البدء سريعًا. لكن المعلومات العامة المتاحة لا توضّح ما إذا كانت الحزمة تدعم نقاط نهاية مخصصة متوافقة مع OpenAI، ولم نتحقق من ذلك؛ لذا لن نتناول هنا كيفية ربطها بمنصات أخرى.

بدلًا من ذلك، سنستخدم نهجًا مختلفًا: لا نجعل شيفرة التطبيق تعتمد مباشرة على حزمة Agent SDK من أي مزود، بل نضيف طبقة خفيفة بينهما تسمى «واجهة التلخيص». تستدعي شيفرة التطبيق الدالة summarize(items) فقط، وتتولى هذه الطبقة تحديد النموذج ونقطة النهاية وفقًا للإعدادات.

تصميم واجهة طبقة الاستدعاء لوكيل ملخصات المراقبة

يمكن تلخيص مبادئ تصميم طبقة الاستدعاء في ثلاث نقاط بسيطة، لكنها توفر الكثير من إعادة العمل لاحقًا:

• إظهار ما يخص التطبيق فقط: توفير الواجهة summarize(items) -> str، دون تمرير المعلمات منخفضة المستوى مثل messages وtemperature إلى شيفرة التطبيق.
• توحيد البروتوكول الأساسي: استخدام تنسيق Chat Completions المتوافق مع OpenAI داخليًا، وقراءة base_url وapi_key وmodel من متغيرات البيئة.
• توفير بديل عند الفشل: إعادة المحاولة عددًا محدودًا من المرات، ثم إخراج قائمة العناوين الأصلية إذا استمر الفشل، لضمان الحصول على نتيجة قابلة للقراءة في ذلك اليوم على الأقل.

اخترنا البروتوكول المتوافق مع OpenAI أساسًا لأنه أصبح عمليًا تنسيقًا شائعًا، كما أن حزمة SDK الرسمية وكثيرًا من أدوات الجهات الخارجية تدعم تعديل base_url. وما دام الخادم متوافقًا مع هذا التنسيق، فلن يتطلب تبديل النموذج سوى تغيير سطر في الإعدادات.

وفقًا لهذا التصميم، يمكن استخدام منصات تجميع مثل APIYI كأحد خيارات طبقة استدعاء النموذج. تتوافق APIYI مع تنسيق OpenAI API وتدعم الاتصال باستخدام SDK الرسمية لـ OpenAI، ولا يتطلب تبديل النموذج سوى تغيير اسمه. بالنسبة إلى وكيل ملخصات المراقبة، يعني ذلك إمكانية مقارنة نتائج التلخيص بين نماذج مختلفة باستخدام مفتاح واحد، دون كتابة شيفرة اتصال منفصلة لكل مزود.

ما الذي ينبغي مراعاته عند اختيار نموذج لمهمة تلخيص نتائج المراقبة؟

قد تبدو مهمة التلخيص بسيطة، لكن متطلبات النموذج تختلف كثيرًا باختلاف مصادر المعلومات. لا تتوفر لدينا حاليًا بيانات اختبار منهجية لهذا النوع من المهام، لذلك لن نحسم أي نموذج هو الأفضل، بل سنستعرض العوامل التي ينبغي الموازنة بينها عند الاختيار.

💡 نصيحة للاختيار: لا توجد إجابة واحدة تناسب الجميع عند اختيار نموذج للتلخيص. الطريقة الأكثر موثوقية هي المقارنة باستخدام مصادر معلوماتك الفعلية لبضعة أيام. يمكنك عبر APIYI apiyi.com التبديل بين عدة نماذج مرشحة باستخدام الشفرة نفسها، ومقارنة استقرار التنسيق وجودة التعبير باللغة الصينية، ثم اختيار النموذج المناسب للاستخدام طويل الأمد.

البدء السريع مع وكيل المراقبة والتلخيص

سنستخدم Python لإنشاء نسخة أولية قابلة للاستخدام. اخترنا واجهة API العامة لـ Hacker News (hacker-news.firebaseio.com/v0) مصدرًا للمعلومات، كما في دليل OpenRouter، لتسهيل المقارنة والفهم.

مثال مبسط: جلب العناوين وتلخيصها

تجلب الشفرة التالية عناوين أهم 10 منشورات على Hacker News، ثم تطلب من النموذج تلخيصها بالصينية للتحقق من عمل المسار كاملًا:

import requests
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # OpenAI 兼容端点
)

HN = "https://hacker-news.firebaseio.com/v0"
ids = requests.get(f"{HN}/topstories.json", timeout=10).json()[:10]
titles = [requests.get(f"{HN}/item/{i}.json", timeout=10).json().get("title", "") for i in ids]

resp = client.chat.completions.create(
    model="gpt-4o-mini",  # 示例模型名，以平台模型列表为准
    messages=[{"role": "user", "content": "用中文分 3 点总结这些热帖的主题：\n" + "\n".join(titles)}]
)
print(resp.choices[0].message.content)

يمكن تشغيل هذه الشفرة، لكنها ليست جاهزة للعمل المستمر بعد: فهي لا تستبعد العناصر المكررة، ولا تعالج حالات الفشل، كما أن النموذج ونقطة النهاية محددان داخل الشفرة. تفصل النسخة الكاملة أدناه المكونات الأربعة وتضيف إدارة الحالة.

import json
import os
import time
from pathlib import Path

import openai
import requests

HN = "https://hacker-news.firebaseio.com/v0"
STATE_FILE = Path(os.getenv("STATE_FILE", "seen_ids.json"))
TOP_N = int(os.getenv("TOP_N", "30"))


# ---------- 数据获取器 ----------
def fetch_new_stories(seen: set) -> list:
    ids = requests.get(f"{HN}/topstories.json", timeout=10).json()[:TOP_N]
    items = []
    for i in ids:
        if i in seen:
            continue
        item = requests.get(f"{HN}/item/{i}.json", timeout=10).json() or {}
        if item.get("title"):
            items.append({"id": i, "title": item["title"],
                          "url": item.get("url", ""), "score": item.get("score", 0)})
    return items


# ---------- 状态管理 ----------
def load_seen() -> set:
    return set(json.loads(STATE_FILE.read_text())) if STATE_FILE.exists() else set()

def save_seen(seen: set) -> None:
    STATE_FILE.write_text(json.dumps(sorted(seen)[-2000:]))  # 只保留最近的 ID


# ---------- 摘要器（模型调用层） ----------
class Summarizer:
    def __init__(self):
        self.client = openai.OpenAI(
            api_key=os.environ["LLM_API_KEY"],
            base_url=os.getenv("LLM_BASE_URL", "https://api.apiyi.com/v1"),
        )
        self.model = os.getenv("SUMMARY_MODEL", "gpt-4o-mini")

    def summarize(self, items: list, retries: int = 2) -> str:
        lines = "\n".join(f"- [{x['score']}] {x['title']}" for x in items)
        prompt = ("你是技术资讯编辑。请用中文把下面的 Hacker News 新热帖归纳为 3-5 个主题，"
                  "每个主题一句话，并列出最值得关注的 3 条标题。\n" + lines)
        for attempt in range(retries + 1):
            try:
                resp = self.client.chat.completions.create(
                    model=self.model,
                    messages=[{"role": "user", "content": prompt}],
                    max_tokens=800,
                )
                return resp.choices[0].message.content
            except Exception as e:
                print(f"摘要失败（第 {attempt + 1} 次）：{e}")
                time.sleep(2 ** attempt)
        return "【模型暂不可用，以下为原始标题】\n" + lines  # 降级输出


# ---------- 输出器 ----------
def deliver(text: str) -> None:
    webhook = os.getenv("WEBHOOK_URL")
    if webhook:
        try:
            requests.post(webhook, json={"text": text}, timeout=10).raise_for_status()
            return
        except Exception as e:
            print(f"推送失败，改为落盘：{e}")
    Path(f"digest-{time.strftime('%Y%m%d-%H%M')}.md").write_text(text, encoding="utf-8")


# ---------- 一次运行（由定时器触发） ----------
def run_once() -> None:
    seen = load_seen()
    items = fetch_new_stories(seen)
    if not items:
        print("没有新条目，本轮跳过")
        return
    deliver(Summarizer().summarize(items))
    save_seen(seen | {x["id"] for x in items})


if __name__ == "__main__":
    run_once()

هناك عدة خيارات تصميم مهمة في النسخة الكاملة. أولًا، لا يتيح Summarizer للاستخدام الخارجي سوى summarize، بينما تُقرأ أسماء النموذج ونقطة الاتصال والمفتاح من متغيرات البيئة، وهذا هو فصل طبقة الاستدعاء الذي تناولناه سابقًا. ثانيًا، يحتفظ ملف الحالة بأحدث مجموعة من المعرّفات فقط، حتى لا يستمر حجمه في النمو مع التشغيل طويل الأمد. وأخيرًا، عند فشل النموذج يُعرض العنوان الأصلي، وعند فشل الإرسال تُحفظ النتائج في ملف، لضمان وجود مخرجات يمكن تتبعها في كل دورة.

جدولة تشغيل وكيل ملخص المراقبة

صُمم السكربت بحيث «يعمل مرة واحدة ثم ينتهي»، لذا يمكن إسناد تشغيله إلى cron مباشرةً. يضبط الإعداد التالي تشغيله يوميًا في الساعة 8 صباحًا و8 مساءً:

# crontab -e
0 8,20 * * * cd /opt/hn-digest && LLM_API_KEY=xxx SUMMARY_MODEL=gpt-4o-mini /usr/bin/python3 agent.py >> run.log 2>&1

إذا أردت مقارنة نموذج آخر، فما عليك سوى تغيير SUMMARY_MODEL إلى اسم النموذج المطلوب، دون تعديل أي سطر من الشفرة. وفي بيئة الإنتاج، يُنصح بوضع المفتاح في ملف .env أو خدمة لإدارة المفاتيح، بدلًا من كتابته مباشرةً في crontab.

🚀 نصيحة للبدء السريع: استخدم المثال المبسط أولًا للتأكد من أن مسار العمل يعمل كما ينبغي، ثم انتقل إلى النسخة الكاملة واربطها بـ cron. توفر APIYI عبر apiyi.com رصيدًا تجريبيًا مجانيًا للمستخدمين الجدد، ويكفي مفتاح واحد للتبديل بين نماذج OpenAI وClaude وGemini وغيرها، مما يسهل مقارنة جودة الملخصات في مرحلة بناء النموذج الأولي.

الأسئلة الشائعة FAQ

أهم النقاط حول وكيل المراقبة والتلخيص

• هيكل من أربع مراحل: التشغيل المجدول، وجلب البيانات، والتلخيص بالنموذج، وإخراج النتائج مراحل مستقلة، ما يسهّل استبدالها واستكشاف الأخطاء
• التشغيل ثم الإنهاء أكثر موثوقية: لمهام التلخيص قليلة التكرار، يوفر استخدام cron مع سكربت يُنفّذ مرة واحدة إدارة أسهل من عملية تعمل باستمرار
• الحالة تحدد الجودة: سجّل معرّفات العناصر التي سبق الاطلاع عليها، ولخّص العناصر الجديدة فقط في كل دورة لتجنب التكرار والهدر
• افصل طبقة الاستدعاء: يعتمد منطق التطبيق على واجهة summarize فقط، بينما تُحدَّد إعدادات النموذج ونقطة النهاية والمفتاح من ملف الإعدادات
• اعتمد بروتوكولًا متوافقًا: يتيح التنسيق المتوافق مع OpenAI تبديل النموذج بتغيير سطر واحد في متغيرات البيئة
• اختر النموذج بالتجربة: قارن بين النماذج حسب السياق واتباع التعليمات واللغة والتكلفة والاستقرار. يمكنك التبديل بينها واختبارها باستخدام الشفرة نفسها على APIYI ‏apiyi.com
• وفّر بدائل عند الفشل: إذا فشل النموذج، أعرض العناوين الأصلية؛ وإذا فشل الإرسال، احفظ النتائج على القرص

الخلاصة

عند بناء وكيل يُنشئ ملخصات للمراقبة وفق جدول زمني، لا تكمن الأهمية في استخدام إطار عمل معقد، بل في تقسيم البنية بوضوح:

1. تقسيم المكونات: ترتبط مكونات التشغيل وجلب البيانات والتلخيص والإخراج بهياكل بيانات بسيطة، ويمكن اختبار كل منها على حدة.
2. فصل الواجهات: تُستخدم واجهة تلخيص بسيطة لعزل حزمة SDK المحددة، مع الاعتماد على بروتوكول متوافق مع OpenAI في الطبقة الأساسية.
3. إعطاء الأولوية للاستقرار: إزالة التكرار وإعادة المحاولة والحلول البديلة عناصر ضرورية للمهام التي تعمل دون إشراف.

يقدم دليل OpenRouter الخاص بـ Hacker News مثالًا جيدًا لتطبيق هذه الفكرة، بينما تتيح لك البنية العامة في هذا المقال نقلها إلى أي مصدر معلومات وأي نموذج. والخطوة التالية هي تجربة المسار كاملًا بمثال بسيط، ثم ربطه بـ cron وتشغيله لعدة أيام، ومراقبة جودة الملخصات قبل اختيار نموذج للاستخدام على المدى الطويل.

ننصح باستخدام APIYI على apiyi.com للتحقق من النتائج سريعًا. يتيح لك مفتاح API واحد التبديل بين عدة نماذج شائعة، كما يحصل المستخدمون الجدد على رصيد تجريبي مجاني لإجراء اختبارات مقارنة خلال مرحلة بناء النموذج الأولي.

📚 المراجع

1. ملخص دليل OpenRouter: إنشاء وكيل ذكاء اصطناعي دائم لمراقبة Hacker News باستخدام Agent SDK
2. الرابط: aihot.news/items/upl3hjjdokqe13w3ieo9opr0v

3. الوصف: مقدمة المقال، وتعرض مثالًا على إنشاء وكيل يعمل وفق جدول زمني باستخدام @openrouter/agent الإصدار 0.11.0 في TypeScript

4. واجهة API الرسمية لـ Hacker News: واجهة بيانات عامة للقراءة فقط

5. الرابط: github.com/HackerNews/API

6. الوصف: تتضمن شرحًا لحقول واجهات مثل topstories وitem، وهي توثيق مصدر البيانات المستخدم في أمثلة المقال

7. حزمة OpenAI Python SDK: مكتبة العميل الرسمية

8. الرابط: github.com/openai/openai-python
9. الوصف: تشرح كيفية الاتصال بنقاط النهاية المتوافقة باستخدام المعامل base_url

الكاتب: الفريق التقني في APIYI
للتواصل التقني: يسعدنا تواصلكم معنا عبر الصفحة الرئيسية لموقع APIYI، ويمكنكم زيارة مركز التوثيق على docs.apiyi.com للاطلاع على المزيد من موارد التكامل

مقالات ذات صلة

• تعطّل Google Cloud في لندن لمدة 7 ساعات و52 دقيقة: لا تجعل أعمالك تعتمد على نموذج واحد فقط: انقطع التيار في إحدى مناطق التوافر التابعة لـ Google Cloud في لندن لمدة 7 ساعات و52 دقيقة، كما تعطلت DeepSeek قبل بضعة أيام لمدة 4 ساعات و52 دقيقة؛ فالنموذج حلقة في سير العمل، وتجهيز مسار ثانٍ وثالث مسبقاً أنفع من انتظار إصلاح الخدمة upstream.
• مقارنة بين المهام المجدولة في ChatGPT ووكيل Codex والأتمتة الكاملة في Dot: 6 اختلافات جوهرية بين 3 أنواع من الأتمتة: قارن بين المهام المجدولة في ChatGPT ووكيل Codex وChatGPT Dot من حيث الأتمتة الكاملة والتكلفة والموثوقية وتوصيات الاختيار، على ثلاثة مستويات: التفعيل والتنفيذ والتنسيق المستمر.
• حل مشكلة الشرائط الملونة في الصور المُولَّدة باستخدام GPT image 2.5: تشخيص 5 أنواع من الشرائط الملونة ودليل اختيار مَعلمة الجودة: حلّل خمسة أنواع وأسباب ظهور الأشرطة والضوضاء الملوّنة عند توليد الصور بـgpt-image-2.5-sunburst، واشرح علاقة مستويات الجودة بميزانية القدرة الحاسوبية، وقدّم تحويلًا للمستويات وفق «2.5 high ≈ 2 medium» ومقارنة للتكلفة وحلولًا لإزالتها دون زيادة كبيرة في الميزانية.