Skip to content

Build and run agents you can see, understand and trust.

fix(embedding): keep the cache when a batch cannot fit its size limit (#2790)

sxh60723b929e1f
diff --git a/src/agentscope/embedding/_file_cache.py b/src/agentscope/embedding/_file_cache.py
index 11b6f8dba..da52cc567 100644
--- a/src/agentscope/embedding/_file_cache.py
+++ b/src/agentscope/embedding/_file_cache.py
@@ -37,7 +37,8 @@ class FileEmbeddingCache(EmbeddingCacheBase):
max_cache_size (`int | None`, defaults to `None`):
The maximum size of the cache directory in MB. If exceeded,
the oldest files will be removed until the size is within the
- limit.
+ limit. A vector set that exceeds the limit on its own is not
+ cached, so that storing it cannot empty the cache.
"""
self._cache_dir = os.path.abspath(cache_dir)
self.max_file_number = max_file_number
@@ -81,10 +82,10 @@ class FileEmbeddingCache(EmbeddingCacheBase):
if overwrite:
np.save(path_file, embeddings)
- await self._maintain_cache_dir()
+ await self._maintain_cache_dir(path_file)
else:
np.save(path_file, embeddings)
- await self._maintain_cache_dir()
+ await self._maintain_cache_dir(path_file)
async def retrieve(
self,
@@ -145,10 +146,35 @@ class FileEmbeddingCache(EmbeddingCacheBase):
json_str = json.dumps(identifier, ensure_ascii=False)
return hashlib.sha256(json_str.encode("utf-8")).hexdigest() + ".npy"
- async def _maintain_cache_dir(self) -> None:
+ async def _maintain_cache_dir(
+ self,
+ new_file: str | None = None,
+ ) -> None:
"""Maintain the cache directory by removing old files if the number of
files exceeds the maximum limit or if the cache size exceeds the
- maximum size."""
+ maximum size.
+
+ Args:
+ new_file (`str | None`, defaults to `None`):
+ The path of the file that :meth:`store` has just written.
+ When that file alone is larger than ``max_cache_size`` it is
+ dropped uncached and the rest of the cache is left untouched:
+ evicting oldest-first towards such a limit would delete
+ every other file and still not fit.
+ """
+ if new_file and self.max_cache_size is not None:
+ new_size_mb = os.path.getsize(new_file) / (1024.0 * 1024.0)
+ if new_size_mb > self.max_cache_size:
+ os.remove(new_file)
+ logger.warning(
+ "Do not cache %s: it holds %.2f MB, which exceeds the "
+ "%d MB cache limit on its own.",
+ os.path.basename(new_file),
+ new_size_mb,
+ self.max_cache_size,
+ )
+ return
+
files = [
(_.name, _.stat().st_mtime)
for _ in os.scandir(self.cache_dir)
diff --git a/tests/embedding_file_cache_test.py b/tests/embedding_file_cache_test.py
new file mode 100644
index 000000000..f98788365
--- /dev/null
+++ b/tests/embedding_file_cache_test.py
@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for :class:`FileEmbeddingCache` eviction limits."""
+import os
+import tempfile
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.embedding import FileEmbeddingCache
+
+WIDTH = 1536
+
+
+def _vectors(count: int) -> list:
+ """Build an embeddings list of the given number of vectors.
+
+ Args:
+ count (`int`):
+ The number of vectors to build.
+
+ Returns:
+ `list`:
+ A list of float vectors, about ``count * 12`` KB on disk.
+ """
+ return [[float(row)] * WIDTH for row in range(count)]
+
+
+class FileEmbeddingCacheEvictionTest(IsolatedAsyncioTestCase):
+ """The size limit must never cost more entries than it stores."""
+
+ async def test_oversized_entry_is_not_cached_and_keeps_the_cache(
+ self,
+ ) -> None:
+ """An entry too large to ever fit is skipped, not cached by force."""
+ with tempfile.TemporaryDirectory() as cache_dir:
+ cache = FileEmbeddingCache(cache_dir=cache_dir, max_cache_size=1)
+ await cache.store(_vectors(10), "seed")
+
+ await cache.store(_vectors(200), "oversized")
+
+ self.assertEqual(
+ os.listdir(cache_dir),
+ [FileEmbeddingCache._get_filename("seed")],
+ )
+ self.assertEqual(await cache.retrieve("seed"), _vectors(10))
+ self.assertIsNone(await cache.retrieve("oversized"))
+
+ async def test_later_entries_are_still_cached_after_an_oversized_one(
+ self,
+ ) -> None:
+ """A skipped oversized entry leaves the cache usable."""
+ with tempfile.TemporaryDirectory() as cache_dir:
+ cache = FileEmbeddingCache(cache_dir=cache_dir, max_cache_size=1)
+ await cache.store(_vectors(200), "oversized")
+ await cache.store(_vectors(10), "after")
+
+ self.assertEqual(await cache.retrieve("after"), _vectors(10))
+
+ async def test_size_limit_still_evicts_the_oldest_entries(self) -> None:
+ """Fitting a new entry keeps evicting oldest-first, newest intact."""
+ with tempfile.TemporaryDirectory() as cache_dir:
+ cache = FileEmbeddingCache(cache_dir=cache_dir, max_cache_size=1)
+ identifiers = [f"entry-{index}" for index in range(12)]
+ for index, identifier in enumerate(identifiers):
+ await cache.store(_vectors(10), identifier)
+ # Pin the modification times so the eviction order does not
+ # depend on how coarse the filesystem timestamp is.
+ path = os.path.join(
+ cache_dir,
+ FileEmbeddingCache._get_filename(identifier),
+ )
+ os.utime(path, (1000 + index, 1000 + index))
+
+ present = [
+ await cache.retrieve(identifier) is not None
+ for identifier in identifiers
+ ]
+
+ # Eviction only ever takes from the oldest end, so the surviving
+ # entries form a suffix of the insertion order.
+ removed = present.count(False)
+ self.assertEqual(
+ present,
+ [False] * removed + [True] * (len(present) - removed),
+ )
+ self.assertGreater(removed, 0)
+ self.assertTrue(present[-1])
+ self.assertEqual(
+ await cache.retrieve("entry-11"),
+ _vectors(10),
+ )
+ self.assertLessEqual(cache._get_cache_size(), 1)