Upstash redis integration (#10871)

- **Description:** Introduced Upstash provider with following wrappers: UpstashRedisCache, UpstashRedisEntityStore, UpstashRedisChatMessageHistory, UpstashRedisStore - **Issue:** -, - **Dependencies:** upstash-redis python package is needed, - **Tag maintainer:** @baskaryan - **Twitter handle:** @BurakY744 --------- Co-authored-by: Burak Yılmaz <burakyilmaz@Buraks-MacBook-Pro.local> Co-authored-by: Bagatur <baskaryan@gmail.com>
2025-09-07 05:52:15 +00:00 · 2023-10-13 03:36:51 +03:00
parent a9db2b0b92
commit 63e516c2b0
17 changed files with 923 additions and 35 deletions
--- a/docs/docs/integrations/llms/llm_caching.ipynb
+++ b/docs/docs/integrations/llms/llm_caching.ipynb
@@ -12,7 +12,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 3,
   "id": "10ad9224",
   "metadata": {},
   "outputs": [],
@@ -37,7 +37,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 4,
   "id": "426ff912",
   "metadata": {},
   "outputs": [],
@@ -207,6 +207,101 @@
    "llm(\"Tell me a joke\")"
   ]
  },
+  {
+   "cell_type": "markdown",
+   "id": "e71273ab",
+   "metadata": {},
+   "source": [
+    "## `Upstash Redis` Cache"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f10dabef",
+   "metadata": {},
+   "source": [
+    "### Standard Cache\n",
+    "Use [Upstash Redis](https://upstash.com) to cache prompts and responses with a serverless HTTP API."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "f3920f25",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from upstash_redis import Redis\n",
+    "from langchain.cache import UpstashRedisCache\n",
+    "\n",
+    "URL = \"<UPSTASH_REDIS_REST_URL>\"\n",
+    "TOKEN = \"<UPSTASH_REDIS_REST_TOKEN>\"\n",
+    "\n",
+    "langchain.llm_cache = UpstashRedisCache(redis_=Redis(url=URL, token=TOKEN))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 39,
+   "id": "3bf7d959",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "CPU times: user 7.56 ms, sys: 2.98 ms, total: 10.5 ms\n",
+      "Wall time: 1.14 s\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'\\n\\nWhy did the chicken cross the road?\\n\\nTo get to the other side!'"
+      ]
+     },
+     "execution_count": 39,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "%%time\n",
+    "# The first time, it is not yet in cache, so it should take longer\n",
+    "llm(\"Tell me a joke\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 50,
+   "id": "00fc3a34",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "CPU times: user 2.78 ms, sys: 1.95 ms, total: 4.73 ms\n",
+      "Wall time: 82.9 ms\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'\\n\\nTwo guys stole a calendar. They got six months each.'"
+      ]
+     },
+     "execution_count": 50,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "%%time\n",
+    "# The first time, it is not yet in cache, so it should take longer\n",
+    "llm(\"Tell me a joke\")"
+   ]
+  },
  {
   "cell_type": "markdown",
   "id": "278ad7ae",
@@ -229,7 +324,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
   "id": "39f6eb0b",
   "metadata": {},
   "outputs": [],
@@ -244,7 +339,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": null,
   "id": "28920749",
   "metadata": {},
   "outputs": [
@@ -440,7 +535,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": null,
   "id": "9e4ecfd1",
   "metadata": {},
   "outputs": [
--- a/docs/docs/integrations/memory/upstash_redis_chat_message_history.ipynb
+++ b/docs/docs/integrations/memory/upstash_redis_chat_message_history.ipynb
@@ -0,0 +1,61 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Upstash Redis Chat Message History\n",
+    "\n",
+    "This notebook goes over how to use Upstash Redis to store chat message history."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.memory.chat_message_histories.upstash_redis import UpstashRedisChatMessageHistory\n",
+    "\n",
+    "URL = \"<UPSTASH_REDIS_REST_URL>\"\n",
+    "TOKEN = \"<UPSTASH_REDIS_REST_TOKEN>\"\n",
+    "\n",
+    "history = UpstashRedisChatMessageHistory(url=URL, token=TOKEN, ttl=10, session_id=\"my-test-session\")\n",
+    "\n",
+    "history.add_user_message(\"hello llm!\")\n",
+    "history.add_ai_message(\"hello user!\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "history.messages"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.3"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
--- a/docs/docs/integrations/providers/upstash.mdx
+++ b/docs/docs/integrations/providers/upstash.mdx
@@ -0,0 +1,42 @@
+# Upstash Redis
+
+Upstash offers developers serverless databases and messaging platforms to build powerful applications without having to worry about the operational complexity of running databases at scale.
+
+This page covers how to use [Upstash Redis](https://upstash.com/redis) with LangChain.
+
+## Installation and Setup
+- Upstash Redis Python SDK can be installed with `pip install upstash-redis`
+- A globally distributed, low-latency and highly available database can be created at the [Upstash Console](https://console.upstash.com)
+
+
+## Integrations
+All of Upstash-LangChain integrations are based on `upstash-redis` Python SDK being utilized as wrappers for LangChain.
+This SDK utilizes Upstash Redis DB by giving UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN parameters from the console.
+One significant advantage of this is that, this SDK uses a REST API. This means, you can run this in serverless platforms, edge or any platform that does not support TCP connections.
+
+
+### Cache
+
+[Upstash Redis](https://upstash.com/redis) can be used as a cache for LLM prompts and responses.
+
+To import this cache:
+```python
+from langchain.cache import UpstashRedisCache
+```
+
+To use with your LLMs:
+```python
+import langchain
+from upstash_redis import Redis
+
+URL = "<UPSTASH_REDIS_REST_URL>"
+TOKEN = "<UPSTASH_REDIS_REST_TOKEN>"
+
+langchain.llm_cache = UpstashRedisCache(redis_=Redis(url=URL, token=TOKEN))
+```
+
+### Memory
+Upstash Redis can be used to persist LLM conversations.
+
+#### Chat Message History Memory
+An example of Upstash Redis for caching conversation message history can be seen in [this notebook](/docs/integrations/memory/upstash_redis_chat_message_history.html).
--- a/docs/docs/modules/data_connection/text_embedding/caching_embeddings.ipynb
+++ b/docs/docs/modules/data_connection/text_embedding/caching_embeddings.ipynb
@@ -23,14 +23,14 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 7,
   "id": "a463c3c2-749b-40d1-a433-84f68a1cd1c7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
-    "from langchain.storage import InMemoryStore, LocalFileStore, RedisStore\n",
+    "from langchain.storage import InMemoryStore, LocalFileStore, RedisStore, UpstashRedisStore\n",
    "from langchain.embeddings import OpenAIEmbeddings, CacheBackedEmbeddings"
   ]
  },
@@ -46,7 +46,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
   "id": "9e4314d8-88ef-4f52-81ae-0be771168bb6",
   "metadata": {},
   "outputs": [],
@@ -59,7 +59,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": null,
   "id": "3e751f26-9b5b-4c10-843a-d784b5ea8538",
   "metadata": {},
   "outputs": [],
@@ -69,7 +69,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": null,
   "id": "30743664-38f5-425d-8216-772b64e7f348",
   "metadata": {},
   "outputs": [],
@@ -91,7 +91,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": null,
   "id": "f9ad627f-ced2-4277-b336-2434f22f2c8a",
   "metadata": {},
   "outputs": [
@@ -120,7 +120,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": null,
   "id": "cf958ac2-e60e-4668-b32c-8bb2d78b3c61",
   "metadata": {},
   "outputs": [],
@@ -140,7 +140,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": null,
   "id": "3a1d7bb8-3b72-4bb5-9013-cf7729caca61",
   "metadata": {},
   "outputs": [
@@ -168,7 +168,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": null,
   "id": "714cb2e2-77ba-41a8-bb83-84e75342af2d",
   "metadata": {},
   "outputs": [
@@ -196,7 +196,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": null,
   "id": "f2ca32dd-3712-4093-942b-4122f3dc8a8e",
   "metadata": {},
   "outputs": [
@@ -232,7 +232,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": null,
   "id": "13bd1c5b-b7ba-4394-957c-7d5b5a841972",
   "metadata": {
    "tags": []
@@ -244,7 +244,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": null,
   "id": "9d99885f-99e1-498c-904d-6db539ac9466",
   "metadata": {
    "tags": []
@@ -259,7 +259,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": null,
   "id": "682eb5d4-0b7a-4dac-b8fb-3de4ca6e421c",
   "metadata": {
    "tags": []
@@ -289,7 +289,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": null,
   "id": "f819c3ff-a212-4d06-a5f7-5eb1435c1feb",
   "metadata": {
    "tags": []
@@ -311,7 +311,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": null,
   "id": "ec38fb72-90a9-4687-a483-c62c87d1f4dd",
   "metadata": {
    "tags": []
@@ -344,7 +344,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": null,
   "id": "a0070271-0809-4528-97e0-2a88216846f3",
   "metadata": {
    "tags": []
@@ -356,7 +356,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": null,
   "id": "0b20e9fe-f57f-4d7c-9f81-105c5f8726f4",
   "metadata": {
    "tags": []
@@ -370,7 +370,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 21,
+   "execution_count": null,
   "id": "630515fd-bf5c-4d9c-a404-9705308f3a2c",
   "metadata": {
    "tags": []
@@ -392,7 +392,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 22,
+   "execution_count": null,
   "id": "30e6bb87-42c9-4d08-88ac-0d22c9c449a1",
   "metadata": {
    "tags": []
@@ -424,7 +424,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 23,
+   "execution_count": null,
   "id": "658e2914-05e9-44a3-a8fe-3fe17ca84039",
   "metadata": {},
   "outputs": [
@@ -444,6 +444,86 @@
    "list(fs.yield_keys())"
   ]
  },
+  {
+   "cell_type": "markdown",
+   "id": "904c1d47",
+   "metadata": {},
+   "source": [
+    "## Upstash Redis Store"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d0f9f212",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.storage.upstash_redis import UpstashRedisStore"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "45bf62e4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from upstash_redis import Redis\n",
+    "URL = \"<UPSTASH_REDIS_REST_URL>\"\n",
+    "TOKEN = \"<UPSTASH_REDIS_REST_TOKEN>\"\n",
+    "\n",
+    "redis_client = Redis(url=URL, token=TOKEN)\n",
+    "store = UpstashRedisStore(client=redis_client, ttl=None, namespace=\"test-ns\")\n",
+    "\n",
+    "underlying_embeddings = OpenAIEmbeddings()\n",
+    "embedder = CacheBackedEmbeddings.from_bytes_store(\n",
+    "    underlying_embeddings, store, namespace=underlying_embeddings.model\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3eac3504",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%time\n",
+    "embeddings = embedder.embed_documents([\"welcome\", \"goodbye\"])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "085dcd30",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%time\n",
+    "embeddings = embedder.embed_documents([\"welcome\", \"goodbye\"])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3570e83f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "list(store.yield_keys())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d7dc8e51",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "list(store.client.scan(0))"
+   ]
+  },
  {
   "cell_type": "markdown",
   "id": "cd5f5a96-6ffa-429d-aa82-00b3f6532871",
@@ -455,7 +535,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 24,
+   "execution_count": null,
   "id": "4879c134-141f-48a0-acfe-7d6f30253af0",
   "metadata": {},
   "outputs": [],
@@ -465,7 +545,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 25,
+   "execution_count": null,
   "id": "8b2bb9a0-6549-4487-8532-29ab4ab7336f",
   "metadata": {},
   "outputs": [],
@@ -482,7 +562,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 26,
+   "execution_count": null,
   "id": "eca3cb99-2bb3-49d5-81f9-1dee03da4b8c",
   "metadata": {},
   "outputs": [
@@ -502,7 +582,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 27,
+   "execution_count": null,
   "id": "317ba5d8-89f9-462c-b807-ad4ef26e518b",
   "metadata": {},
   "outputs": [
@@ -522,7 +602,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": null,
   "id": "8a540317-5142-4491-9062-a097932b56e3",
   "metadata": {},
   "outputs": [
@@ -544,7 +624,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": null,
   "id": "cd9b0d4a-f816-4dce-9dde-cde1ad9a65fb",
   "metadata": {},
   "outputs": [
@@ -581,7 +661,7 @@
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
-   "version": "3.9.1"
+   "version": "3.11.3"
  }
 },
 "nbformat": 4,