167 lines
No EOL
8.5 KiB
Text
167 lines
No EOL
8.5 KiB
Text
---
|
|
title: Quickstart
|
|
slug: /quickstart
|
|
---
|
|
|
|
import Icon from "@site/src/components/icon/icon";
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
import PartialWsl from '@site/docs/_partial-wsl-install.mdx';
|
|
import PartialIntegrateChat from '@site/docs/_partial-integrate-chat.mdx';
|
|
|
|
Use this quickstart to install OpenRAG, and then try some of OpenRAG's core features.
|
|
|
|
## Prerequisites
|
|
|
|
This quickstart requires the following:
|
|
|
|
- An [OpenAI API key](https://platform.openai.com/api-keys).
|
|
This quickstart uses OpenAI for simplicity.
|
|
For other providers, see the complete [installation guide](/install).
|
|
|
|
- [Python](https://www.python.org/downloads/release/python-3100/) version 3.13 or later.
|
|
|
|
- Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL).
|
|
|
|
<details>
|
|
<summary>Install WSL for OpenRAG</summary>
|
|
|
|
<PartialWsl />
|
|
|
|
</details>
|
|
|
|
|
|
## Install OpenRAG
|
|
|
|
For this quickstart, install OpenRAG with the automatic installer script and basic setup:
|
|
|
|
1. Create a directory to store the OpenRAG configuration files, and then change to that directory:
|
|
|
|
```bash
|
|
mkdir openrag-workspace
|
|
cd openrag-workspace
|
|
```
|
|
|
|
2. [Download the OpenRAG install script](https://docs.openr.ag/files/run_openrag_with_prereqs.sh), move it to your OpenRAG directory, and then run it:
|
|
|
|
```bash
|
|
bash run_openrag_with_prereqs.sh
|
|
```
|
|
|
|
This script installs OpenRAG and its dependencies, including Docker or Podman, and it creates a `.env` file and `docker-compose` files in the current working directory.
|
|
You might be prompted to install certain dependencies if they aren't already present in your environment.
|
|
This process can take a few minutes.
|
|
Once the environment is ready, OpenRAG starts.
|
|
|
|
3. Click **Basic Setup**.
|
|
|
|
4. Create passwords for your OpenRAG installation's OpenSearch and Langflow services. You can click **Generate Passwords** to automatically generate passwords.
|
|
|
|
The OpenSearch password is required. The Langflow admin password is optional.
|
|
If you don't generate a Langflow admin password, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) with no password required.
|
|
|
|
Your passwords are saved in the `.env` file that is used to start OpenRAG.
|
|
You can find this file in your OpenRAG installation directory.
|
|
|
|
5. Click **Save Configuration**, and then click **Start All Services**.
|
|
|
|
Wait a few minutes while the startup process pulls and runs the necessary container images.
|
|
Proceed when you see the following messages in the terminal user interface (TUI):
|
|
|
|
```bash
|
|
Services started successfully
|
|
Command completed successfully
|
|
```
|
|
|
|
6. To open the OpenRAG application, go to the TUI main menu, and then click **Open App**.
|
|
Alternatively, in your browser, navigate to `localhost:3000`.
|
|
|
|
7. Select the **OpenAI** model provider, enter your OpenAI API key, and then click **Complete**.
|
|
|
|
For this quickstart, you can use the default options for the model settings.
|
|
|
|
8. Click through the overview slides for a brief introduction to OpenRAG and basic setup, or click <Icon name="ArrowRight" aria-hidden="true"/> **Skip overview**.
|
|
You can complete this quickstart without going through the overview.
|
|
|
|
## Load and chat with documents {#chat-with-documents}
|
|
|
|
Use the [OpenRAG **Chat**](/chat) to explore the documents in your OpenRAG database using natural language queries.
|
|
Some documents are included by default to get you started, and you can load your own documents.
|
|
|
|
1. In OpenRAG, click <Icon name="MessageSquare" aria-hidden="true"/> **Chat**.
|
|
|
|
2. For this quickstart, ask the agent what documents are available.
|
|
For example: `What documents are available to you?`
|
|
|
|
The agent responds with a summary of OpenRAG's default documents.
|
|
|
|
3. To verify the agent's response, click <Icon name="Library" aria-hidden="true"/> **Knowledge** to view the documents stored in the OpenRAG OpenSearch vector database.
|
|
You can click a document to view the chunks of the document as they are stored in the database.
|
|
|
|
4. Click **Add Knowledge** to add your own documents to your OpenRAG knowledge base.
|
|
|
|
For this quickstart, use either the <Icon name="File" aria-hidden="true"/> **File** or <Icon name="Folder" aria-hidden="true"/> **Folder** upload options to load documents from your local machine.
|
|
**Folder** uploads an entire directory.
|
|
The default directory is the `/openrag-documents` subdirectory in your OpenRAG installation directory.
|
|
|
|
For information about the cloud storage provider options, see [Ingest files with OAuth connectors](/ingestion#oauth-ingestion).
|
|
|
|
5. Return to the **Chat** window, and then ask a question related to the documents that you just uploaded.
|
|
|
|
If the agent's response doesn't seem to reference your documents correctly, try the following:
|
|
|
|
* Click <Icon name="Gear" aria-hidden="true"/> **Function Call: search_documents (tool_call)** to view the log of tool calls made by the agent. This is helpful for troubleshooting because it shows you how the agent used particular tools.
|
|
|
|
* Click <Icon name="Library" aria-hidden="true"/> **Knowledge** to confirm that the documents are present in the OpenRAG OpenSearch vector database, and then click each document to see how the document was chunked.
|
|
If a document was chunked improperly, you might need to tweak the ingestion or modify and reupload the document.
|
|
|
|
* Click <Icon name="Settings2" aria-hidden="true"/> **Settings** to modify the knowledge ingestion settings.
|
|
|
|
For more information, see [Configure knowledge](/knowledge) and [Ingest knowledge](/ingestion).
|
|
|
|
## Change the language model and chat settings {#change-components}
|
|
|
|
1. To change the knowledge ingestion settings, agent behavior, or language model, click <Icon name="Settings2" aria-hidden="true"/> **Settings**.
|
|
|
|
The **Settings** page provides quick access to commonly used parameters like the **Language model** and **Agent Instructions**.
|
|
|
|
2. For greater insight into the underlying [Langflow flow](/agents) that drives the OpenRAG chat, click **Edit in Langflow** and then click **Proceed** to launch the Langflow visual editor in a new browser window.
|
|
|
|
If Langflow requests login information, enter the `LANGFLOW_SUPERUSER` and `LANGFLOW_SUPERUSER_PASSWORD` from the `.env` file in your OpenRAG installation directory.
|
|
|
|
The **OpenRAG OpenSearch Agent** flow opens in a new browser window.
|
|
|
|
|
|
|
|
3. For this quickstart, try changing the model.
|
|
Click the **Language Model** component, and then change the **Model Name** to a different OpenAI model.
|
|
|
|
After you edit a built-in flow, you can click **Restore flow** on the **Settings** page to revert the flow to its original state when you first installed OpenRAG.
|
|
|
|
4. Press <kbd>Command</kbd>+<kbd>S</kbd> (<kbd>Ctrl</kbd>+<kbd>S</kbd>) to save your changes.
|
|
|
|
You can close the Langflow browser window, or leave it open if you want to continue experimenting with the flow editor.
|
|
|
|
5. Switch to your OpenRAG browser window, and then click <Icon name="Plus" aria-hidden="true"/> in the **Conversations** tab to start a new conversation.
|
|
This ensures that the chat doesn't persist any context from the previous conversation with the original model.
|
|
|
|
6. Ask the same question you asked in [Load and chat with documents](#chat-with-documents) to see how the response differs from the original model.
|
|
|
|
## Integrate OpenRAG into an application
|
|
|
|
Langflow in OpenRAG includes pre-built flows that you can integrate into your applications using the [Langflow API](https://docs.langflow.org/api-reference-api-examples).
|
|
You can use these flows as-is or modify them to better suit your needs, as demonstrated in [Change the language model and chat settings](#change-components).
|
|
|
|
You can send and receive requests with the Langflow API using Python, TypeScript, or curl.
|
|
|
|
<PartialIntegrateChat />
|
|
|
|
## Next steps
|
|
|
|
* **Reinstall OpenRAG with your preferred settings**: This quickstart used a minimal setup to demonstrate OpenRAG's core functionality.
|
|
It is recommended that you [reinstall OpenRAG](/install#reinstall) with your preferred configuration because some settings are immutable after initial setup.
|
|
For all installation options, see [Install OpenRAG with TUI](/install) and [Install OpenRAG with containers](/docker).
|
|
|
|
* **Learn more about OpenRAG**: Explore OpenRAG and the OpenRAG documentation to learn more about its features and functionality.
|
|
|
|
* **Learn more about Langflow**: For a deep dive on the Langflow API and visual editor, see the [Langflow documentation](https://docs.langflow.org/). |