160 lines
No EOL
8.5 KiB
Text
160 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 PartialIntegrateChat from '@site/docs/_partial-integrate-chat.mdx';
|
|
import PartialPrereqWindows from '@site/docs/_partial-prereq-windows.mdx';
|
|
import PartialPrereqPython from '@site/docs/_partial-prereq-python.mdx';
|
|
|
|
Use this quickstart to install OpenRAG, and then try some of OpenRAG's core features.
|
|
|
|
## Prerequisites
|
|
|
|
<PartialPrereqPython />
|
|
|
|
* Get an [OpenAI API key](https://platform.openai.com/api-keys).
|
|
This quickstart uses OpenAI for simplicity.
|
|
For other providers, see the other [installation methods](/install-options).
|
|
|
|
<PartialPrereqWindows />
|
|
|
|
## Install OpenRAG
|
|
|
|
For this quickstart, install OpenRAG with the automatic installer script and basic setup.
|
|
The script installs OpenRAG dependencies, including Docker or Podman, and then it installs and runs OpenRAG with [`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools).
|
|
|
|
1. Create a directory for your OpenRAG installation, 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
|
|
```
|
|
|
|
Wait while the installer script prepares your environment and installs OpenRAG.
|
|
You might be prompted to install certain dependencies if they aren't already present in your environment.
|
|
|
|
The entire process can take a few minutes.
|
|
Once the environment is ready, the OpenRAG [Terminal User Interface (TUI)](/tui) starts.
|
|
|
|
|
|
|
|
3. In the TUI, click **Basic Setup**.
|
|
|
|
4. Click **Generate Passwords** to create administrator passwords for your OpenRAG OpenSearch and Langflow services.
|
|
|
|
5. Leave the **OpenAI API key** field empty.
|
|
|
|
6. Click **Save Configuration**, and then click **Start All Services**.
|
|
|
|
This process can take some time while OpenRAG pulls and runs the container images.
|
|
If all services start successfully, the TUI prints a confirmation message:
|
|
|
|
```text
|
|
Services started successfully
|
|
Command completed successfully
|
|
```
|
|
|
|
Your OpenRAG configuration and passwords are stored in an [OpenRAG `.env` file](/reference/configuration) file that is created automatically in your OpenRAG installation directory, which is the directory where you ran the installer script.
|
|
Container definitions are stored in the `docker-compose` files in the same directory.
|
|
|
|
7. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.
|
|
|
|
8. From the TUI main menu, click **Open App** to launch the OpenRAG application and start the application onboarding process.
|
|
|
|
9. For this quickstart, select the **OpenAI** model provider, enter your OpenAI API key, and then click **Complete**. Use the default settings for all other model options.
|
|
|
|
10. Click through the overview slides for a brief introduction to OpenRAG, or click <Icon name="ArrowRight" aria-hidden="true"/> **Skip overview**.
|
|
You can complete this quickstart without going through the overview.
|
|
The overview demonstrates some basic functionality that is covered in the next section and in other parts of the OpenRAG documentation.
|
|
|
|
## 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 `uvx` and a minimal setup to demonstrate OpenRAG's core functionality.
|
|
It is recommended that you [reinstall OpenRAG](/reinstall) with your preferred configuration and [installation method](/install-options).
|
|
|
|
* **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/). |