بخش 9.2 · محیط عملیاتی

کلاس‌های AsyncPostgresSaver و AsyncPostgresStore به‌همراه بررسی مالکیت

AsyncPostgresSaver, AsyncPostgresStore, and the owner check

فهرست مطالب
  1. یک Pool مشترک برای سه دسته سطر مختلف
  2. بررسی مالکیت
  3. کاربر از کانتکست خوانده می‌شود
  4. ایزوله‌سازی، در عمل و با سنجش دقیق
  5. حجم داده‌ای که یک گفت‌وگو ذخیره می‌کند

نه چک‌پوینتر کاربر را می‌شناسد و نه Store؛ بنابراین بررسی مالکیت رشته‌گفت‌وگو (Thread) را در روت (Route) انجام دهید و شناسه‌ی کاربر را از کانتکست اجرا بگیرید، هرگز از مدل نگیرید.

مشتری دومی ثبت‌نام می‌کند. کلاینت او شناسه‌ی رشته‌گفت‌وگویی را که در لاگ‌ها دیده می‌فرستد و وضعیت همان رشته‌گفت‌وگو را می‌خواهد. AsyncPostgresSaver آن را برمی‌گرداند؛ چون سطر چک‌پوینت فقط یک شناسه‌ی رشته‌گفت‌وگو دارد و هیچ مشخصه‌ای از هویت فرد در آن نیست. همین موضوع درباره‌ی AsyncPostgresStore هم صدق می‌کند که داده‌ها را بر اساس فضای نامِ (Namespace) انتخابی شما کلیدگذاری می‌کند.

پس از پایان این بخش، می‌توانید چک‌پوینتر، Store و جدول‌های اختصاصی خودتان را روی یک Pool اتصال مشترک بالا بیاورید. همچنین می‌توانید بررسی مالکیتی را که این Saverها ندارند اضافه کنید و دسترسی هر ابزار را فقط به سطرهای متعلق به همان کاربر محدود نگه دارید.

یک Pool مشترک برای سه دسته سطر مختلف

چک‌پوینتر: Saverای که وضعیت هر رشته‌گفت‌وگو را پس از هر گام می‌نویسد؛ در اینجا AsyncPostgresSaver. Store: Saver کلید-مقداری برای داده‌هایی که عمری فراتر از یک رشته‌گفت‌وگو دارند؛ در اینجا AsyncPostgresStore. سرویس ما یک Pool از کتابخانه‌ی psycopg باز می‌کند و در اختیار هر دوی آن‌ها می‌گذارد؛ جدول‌های اختصاصی سرویس هم از همان Pool استفاده می‌کنند.

یک استخر اتصالات مشترک برای چک‌پوینتر، store و جداول برنامه capture/lab/prodapp-mac/code/app/server.py
        kwargs = {"autocommit": True, "prepare_threshold": 0, "row_factory": dict_row}
        locks = await ThreadLocks.connect(settings.database_url)
        async with AsyncConnectionPool(settings.database_url, max_size=settings.pool_max, kwargs=kwargs) as pool:
            checkpointer, store = AsyncPostgresSaver(pool), AsyncPostgresStore(pool)
            async with locks.exclusive("schema-setup"):
                await checkpointer.setup()
                await store.setup()
                await db.setup(pool, set(settings.tokens.values()))

این سه تنظیم در kwargs دقیقاً همان گزینه‌هایی هستند که متد from_conn_string در هر کدام از Saverها به کار می‌برد {{code libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py:87}}. اگر خودتان یک Pool بسازید و ارسال کنید، باید این گزینه‌ها را هم تنظیم کنید: autocommit، prepare_threshold=0 و dict_row.

تنظیم آخر هزینه‌ای هم دارد. ما این را روی مک اندازه گرفتیم: روی اتصالی با prepare_threshold=0، اجرای select 1; select 2 با خطای cannot insert multiple commands into a prepared statement شکست خورد. بدون این تنظیم، دستور اجرا شد. به همین دلیل، برنامه جدول‌هایش را دستور به دستور و تک‌تک می‌سازد.

عملیات راه‌اندازی اولیه تحت یک Advisory Lock در Postgres اجرا می‌شود. اگر این قفل نباشد، دو Worker که هم‌زمان شروع به کار می‌کنند دستورهای مشابه CREATE TABLE و ساخت ایندکس را هم‌زمان اجرا خواهند کرد. اتصال مربوط به این قفل خارج از Pool قرار می‌گیرد؛ دلیل آن را در بخش 9.7 توضیح داده‌ایم.

بررسی مالکیت

سرویس یک جدول اختصاصی به نام threads نگه می‌دارد که در هر سطر آن، یک رشته‌گفت‌وگو و کاربری که آن را ایجاد کرده ثبت شده است. همه‌ی روت‌هایی که نامی از رشته‌گفت‌وگو می‌برند به این تابع وابسته‌اند.

بررسی مالکیت در هر مسیر ترد (thread) capture/lab/prodapp-mac/code/app/server.py
    async def owned(thread_id: str, user_id: str = Depends(user), s: Service = Depends(svc)) -> str:
        async with s.pool.connection() as conn:
            cur = await conn.execute("select user_id from threads where thread_id = %s", (thread_id,))
            row = await cur.fetchone()
        if row is None or row["user_id"] != user_id:
            raise HTTPException(404, "thread not found")
        return thread_id

درخواست برای رشته‌گفت‌وگویی که به کس دیگری تعلق دارد، خطای 404 برمی‌گرداند؛ درست مثل زمانی که رشته‌گفت‌وگو اصلاً وجود ندارد. بازگرداندن خطای 403 به ارسال‌کننده‌ی درخواست لو می‌دهد که چنین شناسه‌ای واقعاً وجود دارد.

این بررسی پاسخ می‌دهد که مالک رشته‌گفت‌وگو کیست. مشخص نمی‌کند چه کسی مجاز به تأیید بازپرداخت وجه (Refund) است؛ بنابراین مشتری‌ای که رشته‌گفت‌وگو را ساخته می‌تواند بازپرداخت آن را هم تأیید کند. در یک سرویس واقعی به هویت جداگانه‌ای برای تأییدکننده نیاز دارید. توکن‌های tok-alice و tok-bob در پیکربندی نمونه صرفاً مقادیر نمایشی هستند؛ حتماً پیش از استقرار، مقادیر اختصاصی خودتان را در AUTH_TOKENS بگذارید.

کاربر از کانتکست خوانده می‌شود

ابزارها هم به کاربر نیاز دارند. مدل یک شناسه‌ی سفارش انتخاب می‌کند و می‌تواند هر رشته‌ای را بفرستد. بنابراین هیچ ابزاری شناسه‌ی کاربر را به عنوان آرگومان ورودی دریافت نمی‌کند. سرویسْ کاربر را در کانتکست اجرا قرار می‌دهد و هر ابزار آن را از runtime.context می‌خواند.

دو ابزاری که دامنه هر پرس‌وجو را به کاربر موجود در context محدود می‌کنند capture/lab/prodapp-mac/code/app/tools.py
async def read_order(order_id: str, runtime: ToolRuntime[Ctx]) -> str:
    """Look up one of the customer's orders by id, for example ORD-alice-1."""
    async with runtime.context.pool.connection() as conn:
        cur = await conn.execute(
            "select id, item, status, total_cents, refunded_cents from orders where id = %s and user_id = %s",
            (order_id, runtime.context.user_id),
        )
…
async def save_note(text: str, runtime: ToolRuntime[Ctx]) -> str:
    """Save a fact or preference about the customer for future conversations."""
    await runtime.store.aput(("memories", runtime.context.user_id), str(uuid.uuid4()), {"text": text})

ما رفتار مدل‌های واقعی را در مواجهه با شناسه‌ی سفارش مشتری دیگر روی مک اندازه گرفتیم. کاربر e05 پرسید: Where is my order ORD-alice-1?. مدل‌های Qwen3 4B و Qwen3 14B هر کدام در هر 3 اجرا، ابزار read_order را با ورودی ORD-alice-1 فراخوانی کردند. Claude Haiku 5.5 هم در تک‌اجرای خود همین کار را کرد. کوئری دیتابیس هیچ سطری برنگرداند، ابزار خطا برگرداند و نام کالا هرگز به وضعیت رشته‌گفت‌وگو نرسید. مدل درخواست داد، اما تنها فیلتر user_id جلویش را گرفت.

ایزوله‌سازی، در عمل و با سنجش دقیق

تست ایزوله‌سازی در مجموعه‌تست ما یک یادداشت را از طریق مدل ذخیره می‌کند؛ اما Qwen3 4B هیچ‌وقت save_note را فراخوانی نکرد. بنابراین آن تست روی مدل 4B چیزی را اثبات نکرد. ما بررسی ایزوله‌سازی را دوباره اجرا کردیم؛ این بار یادداشت را مستقیماً در Store نوشتیم تا به فراخوانی ابزار وابسته نباشد.

ما این را یک بار روی مک با مدل Qwen3 4B اندازه گرفتیم. اسکریپت متن door code is 4471 را در فضای نام ("memories", "alice") ذخیره کرد. سپس alice یک رشته‌گفت‌وگو ساخت و bob با توکن اختصاصی خودش روی آن درخواست فرستاد.

درخواست ارسالی توسط bob نتیجه
GET /threads/{alice's thread}/state 404
POST /threads/{alice's thread}/runs 404
POST /threads/{alice's thread}/approve 404
GET /memories []
What do you remember about me? در رشته‌گفت‌وگوی خودش مدل recall_notes را فراخوانی کرد که [] برگرداند

همین سؤال از طرف alice ابزار recall_notes را فراخوانی کرد و مقدار ["door code is 4471"] برگشت. رشته‌ی 4471 در هیچ کجای وضعیت رشته‌گفت‌وگوی bob نبود. مدل هرگز فضای نام کاربر دیگری را ندید، زیرا ابزارْ فضای نام را از روی کانتکست ساخت.

حجم داده‌ای که یک گفت‌وگو ذخیره می‌کند

ما سطرهای آزمون بارِ بخش 9.7 را با مدل Qwen3 4B اندازه گرفتیم. هر کاربر یک رشته‌گفت‌وگو با چهار اجرا داشت: سؤالی درباره‌ی سفارش، سؤالی متداول، درخواست بازپرداخت و تأیید آن. با 10 کاربر، هر اجرا 27.2 سطر در سه جدول چک‌پوینت نوشت که حدود 20.3 تا 20.4 کیلوبایت داده‌ی خام سطری بود. این نتیجه در هر سه گروه (Cell) ده‌کاربره ثابت ماند. گروه چهارم دوباره اجرا و جایگزین شد. با 50 کاربر، این مقدار به 29.5 تا 30.1 سطر و 21.6 تا 22.1 کیلوبایت رسید؛ زیرا برخی از اجراها به دلیل اتمام مهلت زمانی کلاینت‌ها زودتر متوقف شدند.

در هیچ‌کدام از این سطرها نامی از کاربر برده نمی‌شود. درخواست مربوط به یک رشته‌گفت‌وگو فقط از مسیر بررسی مالکیت به سطرهایش دسترسی پیدا می‌کند، و ابزار هم فقط از طریق کانتکست به سطرهای یک کاربر می‌رسد.

سطرهای یک گفت‌وگو، و اینکه چه کسی می‌تواند آن‌ها را بخواندسطرهای چک‌پوینت فقط شناسه ترد دارند، بنابراین بررسی مالکیت در مسیر و کاربر موجود در کانتکست ابزار تنها لایه‌های جداسازی هستند.
سطرهای سرویس در Postgres و دو بررسی که کاربران را از یکدیگر تفکیک می‌کنند جداول سرویس و فضای‌نام store، همراه با سطرهای نوشته‌شده در هر اجرا در تست بار با 50 کاربر و یک worker: checkpoints با 10.34، checkpoint_blobs با 5.57، checkpoint_writes با 13.67، در مجموع حدود 21.6 کیلوبایت داده در سطرها. درخواستی برای تردِ یک کاربر دیگر، خطای 404 برای state، 404 برای runs و 404 برای approve دریافت کرد. ابزارها شناسه کاربر را از runtime.context می‌خوانند. درخواست HTTP Bearer tok-bob شناسه ترد متعلق به alice owned() threads.user_id برابر با فراخواننده؟ 404 ترد پیدا نشد state, runs, approve no POSTGRES، یک استخر threads thread_id, user_id یک سطر به ازای هر ترد checkpoints thread_id, checkpoint_id 10.34 سطر در هر اجرا checkpoint_blobs thread_id, channel, version 5.57 سطر در هر اجرا checkpoint_writes thread_id, task_id, idx 13.67 سطر در هر اجرا store پیشوند memories.<user>، کلید یک سطر به ازای هر یادداشت orders, refunds, tickets user_id, idempotency_key جداول برنامه خواندن 21.6 کیلوبایت داده در هر اجرا هیچ ستونی نام کاربر ندارد فراخوانی ابزار کاربر از runtime.context recall_notes for bob returned [], and for alice 1 note
هر جعبه یک جدول Postgres یا یک فضای‌نامِ store را با کلید آن و سطرهای نوشته‌شده به ازای هر اجرا در تست بار نشان می‌دهد. فلش‌های مشکی نشان‌دهنده خواندن هستند. نوار کهربایی بررسی مالکیت است. برگرفته از capture/lab/prodapp-mac/summary/load-mac.json و capture/lab/prodapp-mac/summary/service-mac.json.

منابع: capture/lab/prodapp-mac/code/app/server.py، capture/lab/prodapp-mac/code/app/tools.py، capture/lab/prodapp-mac/code/app/db.py، capture/lab/prodapp-mac/code/app/locks.py، capture/lab/prodapp-mac/summary/service-mac.json، capture/lab/prodapp-mac/summary/load-mac.json، capture/lab/prodapp-mac/summary/evals-mac.json، capture/lab/prodapp-mac/runs/service/service-properties.json، capture/lab/prodapp-mac/runs/psycopg-multistatement.txt، capture/lab/prodapp-mac/runs/summary/suite-mac.json؛ فایل‌های libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py و libs/checkpoint-postgres/langgraph/store/postgres/aio.py در نسخه‌ی langgraph-checkpoint-postgres 3.2.1.