diff --git a/docs/concepts/remote_validation_inference.ipynb b/docs/concepts/remote_validation_inference.ipynb index e5b7b332d..459d6af13 100644 --- a/docs/concepts/remote_validation_inference.ipynb +++ b/docs/concepts/remote_validation_inference.ipynb @@ -4,53 +4,74 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Remote Validation Inference\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Guardrails now supports validation through API endpoints! By providing a url when initialized a validator, you are now able to have the validator send a request for ML accelerated validation at an API endpoint. Guardrails has setup a series of endpoints to help you get started.\n" + "# Remote Validation Inference\n", + "\n", + "## The Need\n", + "\n", + "As a concept, guardrailing has a few areas which, when unoptimized, can be extremely latency and resource expensive to run. The main two areas are in guardrailing orchestration and in the ML models used for validating a single guard. These two are resource heavy in slightly different ways. ML models can run with really low latency on GPU-equipped machines, while guardrailing orchestration benefits from general memory and compute resources. Some ML models used for validation run in tens of seconds on CPUs, while they run in milliseconds on GPUs.\n", + "\n", + "## The Guardrails approach\n", + "\n", + "The Guardrails library tackles this problem by providing an interface that allows users to separate the execution of orchestraion from the exeuction of ML-based validation.\n", + "\n", + "The layout of this solution is a simple upgrade to validator libraries themselves. Instead of *always* downloading and installing ML models, they can be configured to reach out to a remote endpoint. This remote endpoint hosts the ML model behind an API that has a uninfied interface for all validator models. Guardrails hosts some of these as a preview feature for free, and users can host their own models as well by following the same interface.\n", + "\n", + "\n", + ":::note\n", + "Remote validation inferencing is only available in Guardrails versions 0.5.0 and above.\n", + ":::" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "To use an guardrails endpoint, you simply need to find a validator that has implemented support. Validators with a Guardrails hosted endpoint are labeled as such on the [Validator Hub](https://hub.guardrailsai.com). One example is ToxicLanguage." + "## Using Guardrails Inferencing Endpoints\n", + "\n", + "To use an guardrails endpoint, you simply need to find a validator that has implemented support. Validators with a Guardrails hosted endpoint are labeled as such on the [Validator Hub](https://hub.guardrailsai.com). One example is ToxicLanguage.\n", + "\n", + "\n", + ":::note\n", + "To use remote inferencing endpoints, you need to have a Guardrails API key. You can get one by signing up at [the Guardrails Hub](https://hub.guardrailsai.com).\n", + "\n", + "Then, run `guardrails configure`\n", + ":::" ] }, { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "shellscript" + } + }, "outputs": [], "source": [ - "!guardrails hub install hub://guardrails/toxic_language --quiet" + "guardrails hub install hub://guardrails/toxic_language --quiet;\n", + "\n", + "# This will not download local models if you opted into remote inferencing during guardrails configure\n", + "# If you did not opt in, you can explicitly opt in for just this validator by passing the --no-install-local-models flag\n" ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": {}, - "outputs": [], "source": [ - "from guardrails import Guard\n", - "from guardrails.hub import ToxicLanguage" + "From here, you can use the validator as you would normally." ] }, { "cell_type": "code", - "execution_count": 10, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ + "from guardrails import Guard\n", + "from guardrails.hub import ToxicLanguage\n", + "\n", "guard = Guard().use(\n", - " ToxicLanguage\n", - " # Uncomment the following line to use a local version of the model\n", - " # To download the model, run `guardrails hub install` with the --install-local-models flag\n", - " # use_local=True\n", + " ToxicLanguage()\n", ")" ] }, @@ -93,7 +114,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "You are also able to host an endpoint! Just implement the required inference logic and host it on your own server.\n" + "## Hosting your own endpoint\n", + "\n", + "Validators are able to point to any endpoint that implements the interface that Guardrails validators expect. This interface can be found in the `_inference_remote` method of the validator.\n", + "\n", + "After implementing this interface, you can host your own endpoint (for example, using gunicorn and Flask) and point your validator to it by setting the `validation_endpoint` constructor argument.\n" ] }, { @@ -103,11 +128,19 @@ "outputs": [], "source": [ "guard = Guard().use(\n", - " ToxicLanguage,\n", - " use_local=False,\n", - " validation_endpoint=\"your_endpoint_ip_address\",\n", + " ToxicLanguage(\n", + " use_local=False,\n", + " validation_endpoint=\"your_endpoint_ip_address\",\n", + " )\n", ")" ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To learn more about writing your own validators, check out the [Custom validators doc](/docs/how_to_guides/custom_validator)." + ] } ], "metadata": { diff --git a/docs/getting_started/guardrails_server.md b/docs/getting_started/guardrails_server.md index 70f99077a..0cae50d5c 100644 --- a/docs/getting_started/guardrails_server.md +++ b/docs/getting_started/guardrails_server.md @@ -3,7 +3,7 @@ import TabItem from '@theme/TabItem'; # Guardrails Server -## Overview +# Overview In Guardrails v0.5.0, we released the Guardrails Server. The Guardrails server unlocks several usecases and programming languages through features like **OpenAI SDK compatible enpdoints**, remote validator executions, and server-side support of custom functions. @@ -11,9 +11,9 @@ Together, these features make it easier to get started, and make it possible to This document will overview a few of the key features of the Guardrails Server, and how to get started. -## Walkthrough +# Walkthrough -### 1. Install the Guardrails Server +## 1. Install the Guardrails Server This is done by simply installing the `guardrails-ai` package. See the [installation guide](./quickstart.md) for more information. ```bash @@ -21,21 +21,21 @@ pip install guardrails-ai; guardrails configure; ``` -### 2. Create a Guardrails config file +## 2. Create a Guardrails config file The Guardrails config file is a python file that includes the Guardrails that you want to use, defined in a `Guard` object. We'll use the `create` command on the guardrails CLI to do this. We'll specify the [GibberishText validator](https://hub.guardrailsai.com/validator/guardrails/gibberish_text) from the Guardrails Hub. ```bash -guardrails create --validators hub://guardrails/gibberish_text +guardrails create --validators hub://guardrails/gibberish_text --name gibberish_guard ``` :::note -This creates a file called config.py with a Guard object that uses the GibberishText validator. The Guard object still needs to be named. +This creates a file called config.py with a Guard object that uses the GibberishText validator. This file can be edited to include more guards, or to change guard behavior. ::: -Update the guard with a Guard name. Also, have the GibberishText validator throw an exception when it is violated. +Update the guard to have the GibberishText validator throw an exception when it is violated. It should look like this ```python from guardrails import Guard @@ -44,7 +44,7 @@ guard = Guard(name='gibberish_guard') guard.use(GibberishText(on_fail='exception')) ``` -### 3. Start the Guardrails Server +## 3. Start the Guardrails Server The guardrails CLI starts the server on `localhost:8000` by default. An API reference can be found at `https://localhost:8000/docs`. Since guards run on the backend, you also want to set LLM API Keys in the environment. ```bash @@ -54,7 +54,9 @@ guardrails start --config config.py Guardrails is now running on localhost:8000. -### 4. Update client to use the Guardrails Server +## 4. Update client to use the Guardrails Server + +### OpenAI SDK Integration You need only route your openai (or openai compatible sdk) base_url to the `http://localhost:8000/guards/[guard_name]/openai/v1/` endpoint. Your client code will now throw an exception if the GibberishText validator is violated. Note, this works in multiple languages. @@ -62,12 +64,13 @@ You need only route your openai (or openai compatible sdk) base_url to the `http ```python -import openai -openai.base_url = ( - "http://localhost:8000/guards/gibberish_guard/openai/v1/" +from openai import OpenAI + +client = OpenAI( + base_url='http://127.0.0.1:8000/guards/gibberish_guard/openai/v1', ) -response = openai.chat.completions.create( +response = client.chat.completions.create( model="gpt-3.5-turbo", messages=[{ "role": "user", @@ -109,6 +112,23 @@ main(); A `guardrails` key is added to the response object, which includes the validation results. ::: +### Advanced Client Usage +Advanced client usage is available in Python. You can point a Guard shim to the Guardrails server and use it as a normal Guard object. + +To do this, you must first set a `use_server` flag in Guardrails settings. + +```python +# Client code +from guardrails import Guard, settings + +settings.use_server = True + +name_guard = Guard(name="gibberish_guard") + +validation_outcome = name_guard.validate("floofy doopy boopy") +``` + + ## Learn More - [Guardrails Server Concepts](../concepts/deploying) - [Guardrails CLI Reference](../cli) diff --git a/docs/how_to_guides/using_llms.md b/docs/how_to_guides/using_llms.md index d22038223..4e99201f2 100644 --- a/docs/how_to_guides/using_llms.md +++ b/docs/how_to_guides/using_llms.md @@ -1,6 +1,8 @@ -# Using LLMs +# Use Supported LLMs -Guardrails has support for 100+ LLMs through its integration with LiteLLM. To interact with a model set the desired LLM API KEY such as the OPENAI_API_KEY and the desired model with the model property. Examples are below for some common ones. +Guardrails has support for 100+ LLMs through its integration with LiteLLM. This integration is really useful because it allows the Guardrails call API to use the same clean interface that LiteLLM and OpenAI use. This means that you can use similar code to make LLM requests with Guardrails as you would with OpenAI. + +To interact with a model, set the desired LLM API KEY such as the OPENAI_API_KEY and the desired model with the model property. Examples are below for some common ones. ## OpenAI diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index 84978658b..ed0b013ed 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -86,7 +86,12 @@ const sidebars = { ], integrations: [ // "integrations/azure_openai", - "integrations/langchain", + // "integrations/langchain", + { + type: "link", + label: "Langchain", + href: "https://www.guardrailsai.com/blog/using-langchain-and-lcel-with-guardrails-ai" + }, { type: "category", label: "Telemetry",