Cảnh báo về lỗi bộ đệm

Cảnh báo khi lần truy cập bộ nhớ đệm nhắc nhở của một lần chạy bị sập giữa các yêu cầu mô hình, do đó, tiền tố có thể lưu trong bộ nhớ đệm đã di chuyển hoặc bộ nhớ đệm của nhà cung cấp đã hết hạn sẽ hiển thị thay vì lặng lẽ sạc lại token mà lẽ ra nó có thể phân phát từ bộ nhớ đệm.

Mặc dù Pydantic AI Harness có trên các bản phát hành 0.x nhưng API có thể thay đổi giữa các bản phát hành nhỏ; khi đó, cảnh báo ngừng sử dụng và hướng dẫn di chuyển ghi chú phát hành sẽ cho bạn (hoặc người đại diện của bạn) biết chính xác cách nâng cấp. Xem chính sách phiên bản.

Những gì nó xem

Bộ nhớ đệm nhắc nhở chỉ phát huy tác dụng khi tiền tố có thể lưu trong bộ nhớ đệm (công cụ, sau đó là hướng dẫn hệ thống, sau đó là lịch sử tin nhắn) vẫn ổn định ở mức byte trong các yêu cầu liên tiếp của một lần chạy. Khi có thứ gì đó di chuyển tiền tố đó -- các công cụ được sắp xếp lại, dấu thời gian được đưa vào hướng dẫn, bước nhảy khối ở cấp độ tuần tự hóa -- nhà cung cấp sẽ tính phí lại các token mà lẽ ra nó đã được phân phát từ bộ nhớ đệm.

Đây là tín hiệu quan sát: nó đọc nhận định của chính nhà cung cấp thay vì đoán từ yêu cầu có cấu trúc. Trên mỗi phản hồi nó đọc usage.cache_read_tokens và theo dõi tiền tố có thể lưu trong bộ nhớ đệm lớn nhất mà quá trình chạy đã thiết lập (cache_read_tokens + cache_write_tokens, dấu nước cao), được đánh dấu bằng câu trả lời (provider_name, model_name). Vì lịch sử tin nhắn chỉ là phần bổ sung nên tiền tố ổn định có nghĩa là mỗi yêu cầu đối với mô hình đó sẽ đọc lại ít nhất những gì yêu cầu trước đó đã lưu vào bộ nhớ đệm; một sự sụt giảm lớn là dấu hiệu có thể quan sát được của một sự sụp đổ.

Khi một yêu cầu đọc lại ít hơn collapse_ratio của tiền tố đã thiết lập, màn hình sẽ phát ra một CacheBustWarning một lần và chốt khóa đó, giữ im lặng về việc thu gọn cho đến khi quá trình đọc lại lành mạnh ổn định lại bộ đệm. Sự sụp đổ kéo dài -- bộ nhớ đệm bị tắt giữa chừng (read == 0, write == 0) hoặc tiền tố di chuyển mọi yêu cầu để nhà cung cấp tiếp tục ghi vào bộ đệm mà không có gì đọc lại -- do đó cảnh báo một lần, không phải trên mọi yêu cầu.

from pydantic_ai import Agent
from pydantic_ai_harness import WarnOnCacheBusts

agent = Agent('anthropic:claude-sonnet-4-5', capabilities=[WarnOnCacheBusts()])
await agent.run('...')  # a CacheBustWarning fires if a cached prefix collapses mid-run

Phán quyết là miễn phí cho nhiều nhà cung cấp -- pyai bình thường hóa mọi nhà cung cấp vào cache_read_tokens / cache_write_tokens lĩnh vực trên RequestUsage.

Chuyển đổi mô hình và hết hạn

Khóa cho mỗi nhà cung cấp và kiểu máy có nghĩa là việc chuyển đổi mô hình giữa chừng không cảnh báo: a FallbackModel chuyển đổi dự phòng hoặc thay đổi mô hình theo từng bước sử dụng khóa bộ đệm khác, do đó màn hình bắt đầu đánh dấu mới cho nó thay vì so sánh với mô hình trước đó. Các dấu được giữ cho mỗi khóa thay vì đặt lại, do đó việc chuyển về mô hình cũ hơn trong bộ nhớ đệm TTL vẫn so sánh với tiền tố của mô hình đó.

Sự sụp đổ có hai hình dạng mà màn hình không thể phân biệt được, do đó cảnh báo đặt tên cho cả hai: tiền tố có thể lưu trong bộ nhớ đệm đã được di chuyển hoặc bộ nhớ đệm của nhà cung cấp đã hết hạn với tiền tố không thay đổi (khoảng cách giữa các yêu cầu dài hơn TTL bộ nhớ đệm - mặc định của Anthropic là 5 phút, được làm mới sau mỗi lần truy cập). Khi khoảng cách kể từ yêu cầu trước đó của cùng một mô hình vượt quá cache_ttl_seconds, thông báo sẽ báo cáo khoảng trống để công cụ dài hoặc tạm dừng phê duyệt không bị nhầm lẫn với tiền tố đã di chuyển. Khoảng cách được tính thời gian cho mỗi mô hình, do đó, việc chuyển đi và quay lại sẽ đo thời gian nhàn rỗi của chính mô hình quay lại chứ không phải bất cứ điều gì chạy ở giữa.

Tùy chọn

• collapse_ratio (mặc định 0.5): cảnh báo khi yêu cầu đọc lại ít hơn phần này của tiền tố đã thiết lập. Bảo thủ theo mặc định nên việc làm tròn thông thường hoặc bỏ lỡ một phần sẽ không kích hoạt; nâng cao về phía 1.0 để cảnh báo về những hồi quy nhỏ hơn. Nó phải lớn hơn 0.0 -- tỷ lệ của 0.0 không bao giờ có thể cảnh báo, vì vậy nó bị từ chối thay vì được coi như một công tắc vô hiệu hóa im lặng.
• min_prefix_tokens (mặc định 1024): chỉ đánh giá sụp đổ khi tiền tố đã thiết lập đạt đến số lượng token này. Dưới kích thước có thể lưu trong bộ nhớ đệm tối thiểu của nhà cung cấp (Anthropic là 1024) cache_read_tokens ồn ào hoặc bằng không.
• cache_ttl_seconds (mặc định 300): TTL bộ nhớ đệm của nhà cung cấp giả định. Chỉ tin nhắn -- khi khoảng cách do yêu cầu trước đó của cùng một mô hình vượt quá nó, cảnh báo lưu ý rằng việc thu gọn có thể là hết hạn bộ đệm chứ không phải là tiền tố đã di chuyển. Nó không thay đổi cho dù cảnh báo có kích hoạt hay không. Giảm mức này cho các nhà cung cấp có thời gian sử dụng bộ nhớ đệm ngắn hơn.

Im lặng và leo thang

Không có API ngăn chặn riêng biệt. Sử dụng stdlib warnings máy móc, chính xác như bạn sẽ quản lý bất kỳ máy móc nào khác UserWarning:

import warnings
from pydantic_ai_harness.warn_on_cache_busts import CacheBustWarning

# Silence the whole category:
warnings.filterwarnings('ignore', category=CacheBustWarning)

# Silence one intentional bust, scoped to the operation that causes it:
with warnings.catch_warnings():
    warnings.simplefilter('ignore', CacheBustWarning)
    result = agent.run_sync('...')  # e.g. a step that switches models or adds a file

# Treat every bust as an error (dev/CI enforcement):
warnings.filterwarnings('error', category=CacheBustWarning)

Trong các thử nghiệm, hãy khẳng định hành vi phá sản có chủ ý với pytest.warns(CacheBustWarning), hoặc tắt tiếng một bài kiểm tra phá hoại hợp pháp với @pytest.mark.filterwarnings('ignore::pydantic_ai_harness.warn_on_cache_busts.CacheBustWarning').

Đốt cháy

Logfire kết nối stdlib logging mô-đun, không phải warnings mô-đun, vì vậy một CacheBustWarning không tự mình đạt được dấu vết của bạn. Để định tuyến các bus vào Logfire, hãy chuyển hướng cảnh báo Python tới logging hệ thống một lần khi khởi động:

import logging

logging.captureWarnings(True)  # warnings.warn(...) -> the 'py.warnings' logger -> Logfire

Tín hiệu của màn hình là CacheBustWarning; định tuyến nó thông qua logging là cách nó tiếp cận Logfire.

Thành phần

• Màn hình chỉ thực hiện for_run và after_model_request; nó không bổ sung thêm công cụ, hướng dẫn hoặc cài đặt mô hình nào, do đó nó kết hợp với bất kỳ khả năng, bộ công cụ hoặc ToolSearch thiết lập mà không bị can thiệp.
• Trạng thái mỗi lần chạy (dấu và thời gian trên mỗi phím) được cụ thể hóa trong for_run, vậy một WarnOnCacheBusts thể hiện có thể được sử dụng lại trên nhiều Agent.run cuộc gọi -- mỗi lần chạy được đánh giá độc lập.

Phạm vi

• Chỉ mang tính chất quan sát. Nó báo cáo rằng tiền tố được lưu trong bộ nhớ đệm bị sập, không phải lý do -- tiền tố đã di chuyển và thời gian hết hạn trong bộ nhớ đệm phía nhà cung cấp trông giống nhau về số lượng token, do đó, cả hai tên cảnh báo đều được đặt tên. Việc giải thích cấu trúc ("điều gì đã di chuyển tiền tố ở lượt này") là một công việc riêng biệt.
• Chỉ kích hoạt khi bộ nhớ đệm được bật và báo cáo. Một lần chạy không bao giờ thiết lập bộ nhớ đệm sẽ không bao giờ cảnh báo.
• Công tắc mô hình đang chạy giữa chừng không cảnh báo. Dấu hiệu tùy theo (provider_name, model_name), vì vậy một FallbackModel chuyển đổi dự phòng bắt đầu một dấu mới thay vì thu gọn mô hình trước đó.

Tham chiếu API

• pydantic_ai_harness.warn_on_cache_busts nguồn
• Khả năng AI của Pydantic
• Móc AI Pydantic

Xuất khẩu mô-đun công khai WarnOnCacheBusts và CacheBustWarning. Nhập chúng từ pydantic_ai_harness.warn_on_cache_busts.

::: pydantic_ai_harness.warn_on_cache_busts.WarnOnCacheBusts

::: pydantic_ai_harness.warn_on_cache_busts.CacheBustWarning