Update docs (#49)
This commit is contained in:
ian_Cin
GitHub
parent
a8725710af
commit
bbe862fe47
153
README.md
153
README.md
|
|
@ -1,9 +1,11 @@
|
|||
# kotaemon
|
||||
|
||||
|
||||
Build and use local RAG-based Question Answering (QA) applications.
|
||||
|
||||
https://github.com/Cinnamon/kotaemon/assets/25688648/815ecf68-3a02-4914-a0dd-3f8ec7e75cd9
|
||||
|
||||
[Source Code](https://github.com/Cinnamon/kotaemon) |
|
||||
[Demo](https://huggingface.co/spaces/lone17/kotaemon-app)
|
||||
[Live Demo](https://huggingface.co/spaces/lone17/kotaemon-app)
|
||||
|
||||
[User Guide](https://cinnamon.github.io/kotaemon/) |
|
||||
[Developer Guide](https://cinnamon.github.io/kotaemon/development/) |
|
||||
|
|
@ -13,9 +15,7 @@
|
|||
[](https://github.com/psf/black)
|
||||
[](https://codeium.com)
|
||||
|
||||
Build and use local RAG-based Question Answering (QA) applications.
|
||||
|
||||
This repository would like to appeal to both end users who want to do QA on their
|
||||
This project would like to appeal to both end users who want to do QA on their
|
||||
documents and developers who want to build their own QA pipeline.
|
||||
|
||||
- For end users:
|
||||
|
|
@ -32,47 +32,150 @@ This repository is under active development. Feedback, issues, and PRs are highl
|
|||
appreciated. Your input is valuable as it helps us persuade our business guys to support
|
||||
open source.
|
||||
|
||||
## Setting up
|
||||
## Installation
|
||||
|
||||
- Clone the repo
|
||||
### For end users
|
||||
|
||||
This document is intended for developers. If you just want to install and use the app as
|
||||
it, please follow the [User Guide](https://cinnamon.github.io/kotaemon/).
|
||||
|
||||
### For developers
|
||||
|
||||
```shell
|
||||
git clone git@github.com:Cinnamon/kotaemon.git
|
||||
cd kotaemon
|
||||
# Create a environment
|
||||
python -m venv kotaemon-env
|
||||
|
||||
# Activate the environment
|
||||
source kotaemon-env/bin/activate
|
||||
|
||||
# Install the package
|
||||
pip install git+https://github.com/Cinnamon/kotaemon.git
|
||||
```
|
||||
|
||||
- Install the environment
|
||||
## Creating your application
|
||||
|
||||
- Create a conda environment (python >= 3.10 is recommended)
|
||||
In order to create your own application, you need to prepare these files:
|
||||
|
||||
- `flowsettings.py`
|
||||
- `app.py`
|
||||
- `.env` (Optional)
|
||||
|
||||
### `flowsettings.py`
|
||||
|
||||
This file contains the configuration of your application. You can use the example
|
||||
[here](https://github.com/Cinnamon/kotaemon/blob/main/libs/ktem/flowsettings.py) as the
|
||||
starting point.
|
||||
|
||||
### `app.py`
|
||||
|
||||
This file is where you create your Gradio app object. This can be as simple as:
|
||||
|
||||
```python
|
||||
from ktem.main import App
|
||||
|
||||
app = App()
|
||||
demo = app.make()
|
||||
demo.launch()
|
||||
```
|
||||
|
||||
### `.env` (Optional)
|
||||
|
||||
This file provides another way to configure your models and credentials.
|
||||
|
||||
<details markdown>
|
||||
|
||||
<summary>Configure model via the .env file</summary>
|
||||
|
||||
Alternatively, you can configure the models via the `.env` file with the information needed to connect to the LLMs. This file is located in
|
||||
the folder of the application. If you don't see it, you can create one.
|
||||
|
||||
Currently, the following providers are supported:
|
||||
|
||||
#### OpenAI
|
||||
|
||||
In the `.env` file, set the `OPENAI_API_KEY` variable with your OpenAI API key in order
|
||||
to enable access to OpenAI's models. There are other variables that can be modified,
|
||||
please feel free to edit them to fit your case. Otherwise, the default parameter should
|
||||
work for most people.
|
||||
|
||||
```shell
|
||||
conda create -n kotaemon python=3.10
|
||||
conda activate kotaemon
|
||||
|
||||
# install dependencies
|
||||
cd libs/kotaemon
|
||||
pip install -e ".[all]"
|
||||
OPENAI_API_BASE=https://api.openai.com/v1
|
||||
OPENAI_API_KEY=<your OpenAI API key here>
|
||||
OPENAI_CHAT_MODEL=gpt-3.5-turbo
|
||||
OPENAI_EMBEDDINGS_MODEL=text-embedding-ada-002
|
||||
```
|
||||
|
||||
- Or run the installer (one of the `scripts/run_*` scripts depends on your OS), then
|
||||
you will have all the dependencies installed as a conda environment at
|
||||
`install_dir/env`.
|
||||
#### Azure OpenAI
|
||||
|
||||
For OpenAI models via Azure platform, you need to provide your Azure endpoint and API
|
||||
key. Your might also need to provide your developments' name for the chat model and the
|
||||
embedding model depending on how you set up Azure development.
|
||||
|
||||
```shell
|
||||
conda activate install_dir/env
|
||||
AZURE_OPENAI_ENDPOINT=
|
||||
AZURE_OPENAI_API_KEY=
|
||||
OPENAI_API_VERSION=2024-02-15-preview
|
||||
AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-35-turbo
|
||||
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT=text-embedding-ada-002
|
||||
```
|
||||
|
||||
- Pre-commit
|
||||
#### Local models
|
||||
|
||||
- Pros:
|
||||
- Privacy. Your documents will be stored and process locally.
|
||||
- Choices. There are a wide range of LLMs in terms of size, domain, language to choose
|
||||
from.
|
||||
- Cost. It's free.
|
||||
- Cons:
|
||||
- Quality. Local models are much smaller and thus have lower generative quality than
|
||||
paid APIs.
|
||||
- Speed. Local models are deployed using your machine so the processing speed is
|
||||
limited by your hardware.
|
||||
|
||||
##### Find and download a LLM
|
||||
|
||||
You can search and download a LLM to be ran locally from the [Hugging Face
|
||||
Hub](https://huggingface.co/models). Currently, these model formats are supported:
|
||||
|
||||
- GGUF
|
||||
|
||||
You should choose a model whose size is less than your device's memory and should leave
|
||||
about 2 GB. For example, if you have 16 GB of RAM in total, of which 12 GB is available,
|
||||
then you should choose a model that takes up at most 10 GB of RAM. Bigger models tend to
|
||||
give better generation but also take more processing time.
|
||||
|
||||
Here are some recommendations and their size in memory:
|
||||
|
||||
- [Qwen1.5-1.8B-Chat-GGUF](https://huggingface.co/Qwen/Qwen1.5-1.8B-Chat-GGUF/resolve/main/qwen1_5-1_8b-chat-q8_0.gguf?download=true):
|
||||
around 2 GB
|
||||
|
||||
##### Enable local models
|
||||
|
||||
To add a local model to the model pool, set the `LOCAL_MODEL` variable in the `.env`
|
||||
file to the path of the model file.
|
||||
|
||||
```shell
|
||||
pre-commit install
|
||||
LOCAL_MODEL=<full path to your model file>
|
||||
```
|
||||
|
||||
- Test
|
||||
Here is how to get the full path of your model file:
|
||||
|
||||
- On Windows 11: right click the file and select `Copy as Path`.
|
||||
</details>
|
||||
|
||||
## Start your application
|
||||
|
||||
Simply run the following command:
|
||||
|
||||
```shell
|
||||
pytest tests
|
||||
python app.py
|
||||
```
|
||||
|
||||
The app will be automatically launched in your browser.
|
||||
|
||||
|
||||
|
||||
## Customize your application
|
||||
|
||||
Please refer to the [Developer Guide](https://cinnamon.github.io/kotaemon/development/)
|
||||
for more details.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,47 @@
|
|||
# Contributing
|
||||
|
||||
## Setting up
|
||||
|
||||
- Clone the repo
|
||||
|
||||
```shell
|
||||
git clone git@github.com:Cinnamon/kotaemon.git
|
||||
cd kotaemon
|
||||
```
|
||||
|
||||
- Install the environment
|
||||
|
||||
- Create a conda environment (python >= 3.10 is recommended)
|
||||
|
||||
```shell
|
||||
conda create -n kotaemon python=3.10
|
||||
conda activate kotaemon
|
||||
|
||||
# install dependencies
|
||||
cd libs/kotaemon
|
||||
pip install -e ".[all]"
|
||||
```
|
||||
|
||||
- Or run the installer (one of the `scripts/run_*` scripts depends on your OS), then
|
||||
you will have all the dependencies installed as a conda environment at
|
||||
`install_dir/env`.
|
||||
|
||||
```shell
|
||||
conda activate install_dir/env
|
||||
```
|
||||
|
||||
- Pre-commit
|
||||
|
||||
```shell
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
- Test
|
||||
|
||||
```shell
|
||||
pytest tests
|
||||
```
|
||||
|
||||
## Package overview
|
||||
|
||||
`kotaemon` library focuses on the AI building blocks to implement a RAG-based QA application. It consists of base interfaces, core components and a list of utilities:
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Getting Started with Kotaemon
|
||||
|
||||
|
||||
|
||||
|
||||
This page is intended for **end users** who want to use the `kotaemon` tool for Question
|
||||
Answering on local documents. If you are a **developer** who wants contribute to the project, please visit the [development](development/index.md) page.
|
||||
|
|
@ -25,9 +25,9 @@ Download and upzip the latest version of `kotaemon` by clicking this
|
|||
|
||||
## Launch
|
||||
|
||||
To launch the app after initial setup or any changes, simply run the `run_*` script again.
|
||||
To launch the app after initial setup or any change, simply run the `run_*` script again.
|
||||
|
||||
A browser window will be opened and greet you with this screen:
|
||||
A browser window will be opened and greets you with this screen:
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -12,9 +12,10 @@ nav:
|
|||
# - Functional description: pages/app/functional-description.md
|
||||
- Development:
|
||||
- development/index.md
|
||||
- Contributing: development/contributing.md
|
||||
# - Data & Data Structure Components: development/data-components.md
|
||||
# - Features: pages/app/features.md
|
||||
- Customize flow logic: pages/app/customize-flows.md
|
||||
- Creating a Component: development/create-a-component.md
|
||||
- Components:
|
||||
- Index:
|
||||
- File index: pages/app/index/file.md
|
||||
|
|
@ -23,8 +24,7 @@ nav:
|
|||
- pages/app/settings/user-settings.md
|
||||
- Extension:
|
||||
- User management: pages/app/ext/user-management.md
|
||||
- Customize flow logic: pages/app/customize-flows.md
|
||||
- Creating a Component: development/create-a-component.md
|
||||
- Contributing: development/contributing.md
|
||||
# generated using gen-files + literate-nav
|
||||
- API Reference: reference/
|
||||
- Issue Tracker: "https://github.com/Cinnamon/kotaemon/issues"
|
||||
|
|
@ -77,6 +77,7 @@ plugins:
|
|||
type: timeago
|
||||
fallback_to_build_date: true
|
||||
- section-index
|
||||
- mkdocs-video
|
||||
|
||||
theme:
|
||||
features:
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user