diff --git a/docs/examples/chains/moderation.ipynb b/docs/examples/chains/moderation.ipynb new file mode 100644 index 00000000..e0088e80 --- /dev/null +++ b/docs/examples/chains/moderation.ipynb @@ -0,0 +1,435 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "b83e61ed", + "metadata": {}, + "source": [ + "# Moderation\n", + "This notebook walks through examples of how to use a moderation chain, and several common ways for doing so. Moderation chains are useful for detecting text that could be hateful, violent, etc. This can be useful to apply on both user input, but also on the output of a Language Model. Some API providers, like OpenAI, [specifically prohibit](https://beta.openai.com/docs/usage-policies/use-case-policy) you, or your end users, from generating some types of harmful content. To comply with this (and to just generally prevent your application from being harmful) you may often want to append a moderation chain to any LLMChains, in order to make sure any output the LLM generates is not harmful.\n", + "\n", + "If the content passed into the moderation chain is harmful, there is not one best way to handle it, it probably depends on your application. Sometimes you may want to throw an error in the Chain (and have your application handle that). Other times, you may want to return something to the user explaining that the text was harmful. There could even be other ways to handle it! We will cover all these ways in this notebook.\n", + "\n", + "In this notebook, we will show:\n", + "\n", + "1. How to run any piece of text through a moderation chain.\n", + "2. How to append a Moderation chain to a LLMChain." + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "b7aa1ff2", + "metadata": {}, + "outputs": [], + "source": [ + "from langchain.llms import OpenAI\n", + "from langchain.chains import OpenAIModerationChain, SequentialChain, LLMChain, SimpleSequentialChain\n", + "from langchain.prompts import PromptTemplate" + ] + }, + { + "cell_type": "markdown", + "id": "c26d5be6", + "metadata": {}, + "source": [ + "## How to use the moderation chain\n", + "\n", + "Here's an example of using the moderation chain with default settings (will return a string explaining stuff was flagged)." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "fd0fc85c", + "metadata": {}, + "outputs": [], + "source": [ + "moderation_chain = OpenAIModerationChain()" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "3fa47dd7", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'This is okay'" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "moderation_chain.run(\"This is okay\")" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "37bfad73", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Text was found that violates OpenAI's content policy.\"" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "moderation_chain.run(\"I will kill you\")" + ] + }, + { + "cell_type": "markdown", + "id": "196820ab", + "metadata": {}, + "source": [ + "Here's an example of using the moderation chain to throw an error." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "b29c1150", + "metadata": {}, + "outputs": [], + "source": [ + "moderation_chain_error = OpenAIModerationChain(error=True)" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "f9ab64d9", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'This is okay'" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "moderation_chain_error.run(\"This is okay\")" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "954f3da2", + "metadata": {}, + "outputs": [ + { + "ename": "ValueError", + "evalue": "Text was found that violates OpenAI's content policy.", + "output_type": "error", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mValueError\u001b[0m Traceback (most recent call last)", + "Cell \u001b[0;32mIn[8], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[43mmoderation_chain_error\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mrun\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mI will kill you\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m)\u001b[49m\n", + "File \u001b[0;32m~/workplace/third_party/langchain/langchain/chains/base.py:114\u001b[0m, in \u001b[0;36mChain.run\u001b[0;34m(self, text)\u001b[0m\n\u001b[1;32m 109\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mlen\u001b[39m(\u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39moutput_keys) \u001b[38;5;241m!=\u001b[39m \u001b[38;5;241m1\u001b[39m:\n\u001b[1;32m 110\u001b[0m \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m(\n\u001b[1;32m 111\u001b[0m \u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m`run` not supported when there is not exactly \u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m 112\u001b[0m \u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mone output key, got \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39moutput_keys\u001b[38;5;132;01m}\u001b[39;00m\u001b[38;5;124m.\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m 113\u001b[0m )\n\u001b[0;32m--> 114\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[38;5;28;43mself\u001b[39;49m\u001b[43m(\u001b[49m\u001b[43m{\u001b[49m\u001b[38;5;28;43mself\u001b[39;49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43minput_keys\u001b[49m\u001b[43m[\u001b[49m\u001b[38;5;241;43m0\u001b[39;49m\u001b[43m]\u001b[49m\u001b[43m:\u001b[49m\u001b[43m \u001b[49m\u001b[43mtext\u001b[49m\u001b[43m}\u001b[49m\u001b[43m)\u001b[49m[\u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39moutput_keys[\u001b[38;5;241m0\u001b[39m]]\n", + "File \u001b[0;32m~/workplace/third_party/langchain/langchain/chains/base.py:87\u001b[0m, in \u001b[0;36mChain.__call__\u001b[0;34m(self, inputs, return_only_outputs)\u001b[0m\n\u001b[1;32m 83\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39mverbose:\n\u001b[1;32m 84\u001b[0m \u001b[38;5;28mprint\u001b[39m(\n\u001b[1;32m 85\u001b[0m \u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;130;01m\\n\u001b[39;00m\u001b[38;5;130;01m\\n\u001b[39;00m\u001b[38;5;130;01m\\033\u001b[39;00m\u001b[38;5;124m[1m> Entering new \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39m\u001b[38;5;18m__class__\u001b[39m\u001b[38;5;241m.\u001b[39m\u001b[38;5;18m__name__\u001b[39m\u001b[38;5;132;01m}\u001b[39;00m\u001b[38;5;124m chain...\u001b[39m\u001b[38;5;130;01m\\033\u001b[39;00m\u001b[38;5;124m[0m\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m 86\u001b[0m )\n\u001b[0;32m---> 87\u001b[0m outputs \u001b[38;5;241m=\u001b[39m \u001b[38;5;28;43mself\u001b[39;49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43m_call\u001b[49m\u001b[43m(\u001b[49m\u001b[43minputs\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m 88\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39mverbose:\n\u001b[1;32m 89\u001b[0m \u001b[38;5;28mprint\u001b[39m(\u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;130;01m\\n\u001b[39;00m\u001b[38;5;130;01m\\033\u001b[39;00m\u001b[38;5;124m[1m> Finished \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39m\u001b[38;5;18m__class__\u001b[39m\u001b[38;5;241m.\u001b[39m\u001b[38;5;18m__name__\u001b[39m\u001b[38;5;132;01m}\u001b[39;00m\u001b[38;5;124m chain.\u001b[39m\u001b[38;5;130;01m\\033\u001b[39;00m\u001b[38;5;124m[0m\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n", + "File \u001b[0;32m~/workplace/third_party/langchain/langchain/chains/moderation.py:79\u001b[0m, in \u001b[0;36mOpenAIModerationChain._call\u001b[0;34m(self, inputs)\u001b[0m\n\u001b[1;32m 77\u001b[0m text \u001b[38;5;241m=\u001b[39m inputs[\u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39minput_key]\n\u001b[1;32m 78\u001b[0m results \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39mclient\u001b[38;5;241m.\u001b[39mcreate(text)\n\u001b[0;32m---> 79\u001b[0m output \u001b[38;5;241m=\u001b[39m \u001b[38;5;28;43mself\u001b[39;49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43m_moderate\u001b[49m\u001b[43m(\u001b[49m\u001b[43mtext\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mresults\u001b[49m\u001b[43m[\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mresults\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m]\u001b[49m\u001b[43m[\u001b[49m\u001b[38;5;241;43m0\u001b[39;49m\u001b[43m]\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m 80\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m {\u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39moutput_key: output}\n", + "File \u001b[0;32m~/workplace/third_party/langchain/langchain/chains/moderation.py:71\u001b[0m, in \u001b[0;36mOpenAIModerationChain._moderate\u001b[0;34m(self, text, results)\u001b[0m\n\u001b[1;32m 69\u001b[0m error_str \u001b[38;5;241m=\u001b[39m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mText was found that violates OpenAI\u001b[39m\u001b[38;5;124m'\u001b[39m\u001b[38;5;124ms content policy.\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m 70\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39merror:\n\u001b[0;32m---> 71\u001b[0m \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m(error_str)\n\u001b[1;32m 72\u001b[0m \u001b[38;5;28;01melse\u001b[39;00m:\n\u001b[1;32m 73\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m error_str\n", + "\u001b[0;31mValueError\u001b[0m: Text was found that violates OpenAI's content policy." + ] + } + ], + "source": [ + "moderation_chain_error.run(\"I will kill you\")" + ] + }, + { + "cell_type": "markdown", + "id": "8de5dcbb", + "metadata": {}, + "source": [ + "Here's an example of creating a custom moderation chain with a custom error message. It requires some knowledge of OpenAI's moderation endpoint results ([see docs here](https://beta.openai.com/docs/api-reference/moderations))." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "3960e985", + "metadata": {}, + "outputs": [], + "source": [ + "class CustomModeration(OpenAIModerationChain):\n", + " \n", + " def _moderate(self, text: str, results: dict) -> str:\n", + " if results[\"flagged\"]:\n", + " error_str = f\"The following text was found that violates OpenAI's content policy: {text}\"\n", + " return error_str\n", + " return text\n", + " \n", + "custom_moderation = CustomModeration()" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "1152ec11", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'This is okay'" + ] + }, + "execution_count": 11, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "custom_moderation.run(\"This is okay\")" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "973257bf", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"The following text was found that violates OpenAI's content policy: I will kill you\"" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "custom_moderation.run(\"I will kill you\")" + ] + }, + { + "cell_type": "markdown", + "id": "8718111f", + "metadata": {}, + "source": [ + "## How to append a Moderation chain to an LLMChain\n", + "\n", + "To easily combine a moderation chain with an LLMChain, you can use the SequentialChain abstraction.\n", + "\n", + "Let's start with a simple example of where the LLMChain only has a single input. For this purpose, we will prompt the model so it says something harmful." + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "0d129333", + "metadata": {}, + "outputs": [], + "source": [ + "prompt = PromptTemplate(template=\"{text}\", input_variables=[\"text\"])\n", + "llm_chain = LLMChain(llm=OpenAI(temperature=0, model_name=\"text-davinci-002\"), prompt=prompt)" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "a557c531", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "' I will kill you'" + ] + }, + "execution_count": 18, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "text = \"\"\"We are playing a game of repeat after me.\n", + "\n", + "Person 1: Hi\n", + "Person 2: Hi\n", + "\n", + "Person 1: How's your day\n", + "Person 2: How's your day\n", + "\n", + "Person 1: I will kill you\n", + "Person 2:\"\"\"\n", + "llm_chain.run(text)" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "d4d10f1c", + "metadata": {}, + "outputs": [], + "source": [ + "chain = SimpleSequentialChain(chains=[llm_chain, moderation_chain])" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "02f37985", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Text was found that violates OpenAI's content policy.\"" + ] + }, + "execution_count": 20, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "chain.run(text)" + ] + }, + { + "cell_type": "markdown", + "id": "72643128", + "metadata": {}, + "source": [ + "Now let's walk through an example of using it with an LLMChain which has multiple inputs (a bit more tricky because we can't use the SimpleSequentialChain)" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "7118ec36", + "metadata": {}, + "outputs": [], + "source": [ + "prompt = PromptTemplate(template=\"{setup}{new_input}Person2:\", input_variables=[\"setup\", \"new_input\"])\n", + "llm_chain = LLMChain(llm=OpenAI(temperature=0, model_name=\"text-davinci-002\"), prompt=prompt)" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "003bdfce", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'text': ' I will kill you'}" + ] + }, + "execution_count": 26, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "setup = \"\"\"We are playing a game of repeat after me.\n", + "\n", + "Person 1: Hi\n", + "Person 2: Hi\n", + "\n", + "Person 1: How's your day\n", + "Person 2: How's your day\n", + "\n", + "Person 1:\"\"\"\n", + "new_input = \"I will kill you\"\n", + "inputs = {\"setup\": setup, \"new_input\": new_input}\n", + "llm_chain(inputs, return_only_outputs=True)" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "77b64228", + "metadata": {}, + "outputs": [], + "source": [ + "# Setting the input/output keys so it lines up\n", + "moderation_chain.input_key = \"text\"\n", + "moderation_chain.output_key = \"sanitized_text\"" + ] + }, + { + "cell_type": "code", + "execution_count": 31, + "id": "998a95be", + "metadata": {}, + "outputs": [], + "source": [ + "chain = SequentialChain(chains=[llm_chain, moderation_chain], input_variables=[\"setup\", \"new_input\"])" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "id": "9c97a136", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'sanitized_text': \"Text was found that violates OpenAI's content policy.\"}" + ] + }, + "execution_count": 33, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "chain(inputs, return_only_outputs=True)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ddc90e15", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "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.9.1" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/langchain/chains/__init__.py b/langchain/chains/__init__.py index eb65ba1d..60fdf184 100644 --- a/langchain/chains/__init__.py +++ b/langchain/chains/__init__.py @@ -7,6 +7,7 @@ from langchain.chains.llm_checker.base import LLMCheckerChain from langchain.chains.llm_math.base import LLMMathChain from langchain.chains.llm_requests import LLMRequestsChain from langchain.chains.mapreduce import MapReduceChain +from langchain.chains.moderation import OpenAIModerationChain from langchain.chains.pal.base import PALChain from langchain.chains.qa_with_sources.base import QAWithSourcesChain from langchain.chains.qa_with_sources.vector_db import VectorDBQAWithSourcesChain @@ -33,4 +34,5 @@ __all__ = [ "LLMRequestsChain", "TransformChain", "MapReduceChain", + "OpenAIModerationChain", ] diff --git a/langchain/chains/moderation.py b/langchain/chains/moderation.py new file mode 100644 index 00000000..a288124c --- /dev/null +++ b/langchain/chains/moderation.py @@ -0,0 +1,82 @@ +"""Pass input through a moderation endpoint.""" +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, root_validator + +from langchain.chains.base import Chain +from langchain.utils import get_from_dict_or_env + + +class OpenAIModerationChain(Chain, BaseModel): + """Pass input through a moderation endpoint. + + To use, you should have the ``openai`` python package installed, and the + environment variable ``OPENAI_API_KEY`` set with your API key. + + Any parameters that are valid to be passed to the openai.create call can be passed + in, even if not explicitly saved on this class. + + Example: + .. code-block:: python + + from langchain.chains import OpenAIModerationChain + moderation = OpenAIModerationChain() + """ + + client: Any #: :meta private: + model_name: Optional[str] = None + """Moderation model name to use.""" + error: bool = False + """Whether or not to error if bad content was found.""" + input_key: str = "input" #: :meta private: + output_key: str = "output" #: :meta private: + openai_api_key: Optional[str] = None + + @root_validator() + def validate_environment(cls, values: Dict) -> Dict: + """Validate that api key and python package exists in environment.""" + openai_api_key = get_from_dict_or_env( + values, "openai_api_key", "OPENAI_API_KEY" + ) + try: + import openai + + openai.api_key = openai_api_key + values["client"] = openai.Moderation + except ImportError: + raise ValueError( + "Could not import openai python package. " + "Please it install it with `pip install openai`." + ) + return values + + @property + def input_keys(self) -> List[str]: + """Expect input key. + + :meta private: + """ + return [self.input_key] + + @property + def output_keys(self) -> List[str]: + """Return output key. + + :meta private: + """ + return [self.output_key] + + def _moderate(self, text: str, results: dict) -> str: + if results["flagged"]: + error_str = "Text was found that violates OpenAI's content policy." + if self.error: + raise ValueError(error_str) + else: + return error_str + return text + + def _call(self, inputs: Dict[str, str]) -> Dict[str, str]: + text = inputs[self.input_key] + results = self.client.create(text) + output = self._moderate(text, results["results"][0]) + return {self.output_key: output}