From 0ad0a034b01a8c5c0c8ea439cab894d0612c8a3e Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Wed, 30 Apr 2025 10:08:19 +0200 Subject: [PATCH 1/7] WIP --- site/content/3.13/data-science/_index.md | 139 +++++++++--------- .../3.13/data-science/adapters/_index.md | 2 +- .../data-science/arangograph-notebooks.md | 2 +- .../3.13/data-science/graph-analytics.md | 2 +- .../{arangographml => graphml}/_index.md | 58 +++++++- .../{arangographml => graphml}/deploy.md | 2 + .../getting-started.md | 3 +- ...{llm-knowledge-graphs.md => hybrid-rag.md} | 52 ++++++- 8 files changed, 178 insertions(+), 82 deletions(-) rename site/content/3.13/data-science/{arangographml => graphml}/_index.md (79%) rename site/content/3.13/data-science/{arangographml => graphml}/deploy.md (98%) rename site/content/3.13/data-science/{arangographml => graphml}/getting-started.md (99%) rename site/content/3.13/data-science/{llm-knowledge-graphs.md => hybrid-rag.md} (73%) diff --git a/site/content/3.13/data-science/_index.md b/site/content/3.13/data-science/_index.md index c543cebc6e..7311f10dcb 100644 --- a/site/content/3.13/data-science/_index.md +++ b/site/content/3.13/data-science/_index.md @@ -3,32 +3,80 @@ title: Data Science menuTitle: Data Science weight: 115 description: >- - ArangoDB lets you apply analytics and machine learning to graph data at scale + ArangoDB lets you aliases: - data-science/overview --- +ArangoDB provides a wide range of functionality that can be utilized for +data science applications. The core database system includes multi-model storage +of information with scalable graph and information retrieval capabilities that +you can directly use for your research and product development. + +ArangoDB also offers a dedicated Data Science Suite, using the database core +as the foundation for higher-level features. Whether you want to turbocharge +generative AI applications with a GraphRAG solution or apply analytics and +machine learning to graph data at scale, ArangoDB covers these needs. + + + +## Data Science Suite + +The Data Science Suite (DSS) is comprised of three major components: + +- [**HybridRAG**](#hybridrag): A complete solution for extracting entities + from text files to create a knowledge graph that you can then query with a + natural language interface. +- [**GraphML**](#graphml): Apply machine learning to graphs for link prediction, + classification, and similar tasks. +- [**Graph Analytics**](#graph-analytics): Run graph algorithms such as PageRank + on dedicated compute resources. + +Each component has an intuitive graphical user interface integrated into the +ArangoDB Platform web interface, guiding you through the process. + + +Alongside these components, you also get the following additional features: -ArangoDB, as the foundation for GraphML, comes with the following key features: +- **Graph visualizer**: A web-based tool for exploring your graph data with an + intuitive interface and sophisticated querying capabilities. +- **Jupyter notebooks**: Run a Jupyter kernel in the platform for hosting + interactive notebooks for experimentation and development of applications + that use ArangoDB as their backend. +- **MLflow integration**: Built-in support for the popular management tool for + the machine learning lifecycle. +- **Adapters**: Use ArangoDB together with cuGraph, NetworkX, and other tools. +- **Application Programming Interfaces**: Use the underlying APIs of the + Data Science Suite services and build your own integrations. -- **Scalable**: designed to support true scalability with high performance for +## From graph to AI + +This section classifies the complexity of the queries you can answer with +ArangoDB and gives you an overview of the respective feature. + +It starts with running a simple query that shows what is the path that goes from +one node to another, continues with more complex tasks like graph classification, +link prediction, and node classification, and ends with generative AI solutions +powered by graph relationships and vector embeddings. + +### Foundational features + +ArangoDB comes with the following key features: + +- **Scalable**: Designed to support true scalability with high performance for enterprise use cases. -- **Simple Ingestion**: easy integration in existing data infrastructure with +- **Simple Ingestion**: Easy integration in existing data infrastructure with connectors to all leading data processing and data ecosystems. -- **Source-Available**: extensibility and community. -- **NLP Support**: built-in text processing, search, and similarity ranking. - -![ArangoDB Machine Learning Architecture](../../images/machine-learning-architecture.png) +- **Source-Available**: Extensibility and community. +- **NLP Support**: Built-in text processing, search, and similarity ranking. -## Graph Analytics vs. GraphML + -This section classifies the complexity of the queries we can answer - -like running a simple query that shows what is the path that goes from one node -to another, or more complex tasks like node classification, -link prediction, and graph classification. +![ArangoDB Machine Learning Architecture](../../images/machine-learning-architecture.png) ### Graph Queries @@ -69,65 +117,24 @@ GraphML can answer questions like: ![Graph ML](../../images/graph-ml.png) For ArangoDB's enterprise-ready, graph-powered machine learning offering, -see [ArangoGraphML](arangographml/_index.md). - -## Use Cases - -This section contains an overview of different use cases where Graph Analytics -and GraphML can be applied. - -### GraphML - -GraphML capabilities of using more data outperform conventional deep learning -methods and **solve high-computational complexity graph problems**, such as: -- Drug discovery, repurposing, and predicting adverse effects. -- Personalized product/service recommendation. -- Supply chain and logistics. - -With GraphML, you can also **predict relationships and structures**, such as: -- Predict molecules for treating diseases (precision medicine). -- Predict fraudulent behavior, credit risk, purchase of product or services. -- Predict relationships among customers, accounts. - -ArangoDB uses well-known GraphML frameworks like -[Deep Graph Library](https://www.dgl.ai) -and [PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/) -and connects to these external machine learning libraries. When coupled to -ArangoDB, you are essentially integrating them with your graph dataset. - -## Example: ArangoFlix - -ArangoFlix is a complete movie recommendation application that predicts missing -links between a user and the movies they have not watched yet. - -This [interactive tutorial](https://colab.research.google.com/github/arangodb/interactive_tutorials/blob/master/notebooks/Integrate_ArangoDB_with_PyG.ipynb) -demonstrates how to integrate ArangoDB with PyTorch Geometric to -build recommendation systems using Graph Neural Networks (GNNs). - -The full ArangoFlix demo website is accessible from the ArangoGraph Insights Platform, -the managed cloud for ArangoDB. You can open the demo website that connects to -your running database from the **Examples** tab of your deployment. +see [ArangoGraphML](graphml/_index.md). -{{< tip >}} -You can try out the ArangoGraph Insights Platform free of charge for 14 days. -Sign up at [dashboard.arangodb.cloud](https://dashboard.arangodb.cloud/home?utm_source=docs&utm_medium=cluster_pages&utm_campaign=docs_traffic). -{{< /tip >}} +### HybridRAG -The ArangoFlix demo uses five different recommendation methods: -- Content-Based using AQL -- Collaborative Filtering using AQL -- Content-Based using ML -- Matrix Factorization -- Graph Neural Networks +HybridRAG is ArangoDB's turn-key solution to turn your organization's data into +a knowledge graph and let everyone utilize the knowledge by asking questions in +natural language. -![ArangoFlix demo](../../images/data-science-arangoflix.png) +HybridRAG combines vector search for retrieving related text snippets +with graph-based retrieval augmented generation (GraphRAG) for context expansion +and relationship discovery. This lets a large language model (LLM) generate +answers that are accurate, context-aware, and chronologically structured. +This approach combats the common problem of hallucination. -The ArangoFlix website not only offers an example of how the user recommendations might -look like in real life, but it also provides information on a recommendation method, -an AQL query, a custom graph visualization for each movie, and more. +To learn more, see the [HybridRAG](hybrid-rag.md) documentation. ## Sample datasets If you want to try out ArangoDB's data science features, you may use the -[`arango_datasets` Python package](../components/tools/arango-datasets.md) +[`arango-datasets` Python package](../components/tools/arango-datasets.md) to load sample datasets into a deployment. diff --git a/site/content/3.13/data-science/adapters/_index.md b/site/content/3.13/data-science/adapters/_index.md index 0aa3efea24..75d8c4558b 100644 --- a/site/content/3.13/data-science/adapters/_index.md +++ b/site/content/3.13/data-science/adapters/_index.md @@ -1,7 +1,7 @@ --- title: Adapters menuTitle: Adapters -weight: 140 +weight: 50 description: >- ArangoDB offers multiple adapters that enable seamless integration with data science tools diff --git a/site/content/3.13/data-science/arangograph-notebooks.md b/site/content/3.13/data-science/arangograph-notebooks.md index 34ca9529be..d6b2a94930 100644 --- a/site/content/3.13/data-science/arangograph-notebooks.md +++ b/site/content/3.13/data-science/arangograph-notebooks.md @@ -1,7 +1,7 @@ --- title: ArangoGraph Notebooks menuTitle: ArangoGraph Notebooks -weight: 130 +weight: 40 description: >- Colocated Jupyter Notebooks within the ArangoGraph Insights Platform --- diff --git a/site/content/3.13/data-science/graph-analytics.md b/site/content/3.13/data-science/graph-analytics.md index 18df401e84..8983a2124e 100644 --- a/site/content/3.13/data-science/graph-analytics.md +++ b/site/content/3.13/data-science/graph-analytics.md @@ -1,7 +1,7 @@ --- title: Graph Analytics menuTitle: Graph Analytics -weight: 123 +weight: 30 description: | ArangoGraph offers Graph Analytics Engines to run graph algorithms on your data separately from your ArangoDB deployments diff --git a/site/content/3.13/data-science/arangographml/_index.md b/site/content/3.13/data-science/graphml/_index.md similarity index 79% rename from site/content/3.13/data-science/arangographml/_index.md rename to site/content/3.13/data-science/graphml/_index.md index 2d5d3324de..96590d719d 100644 --- a/site/content/3.13/data-science/arangographml/_index.md +++ b/site/content/3.13/data-science/graphml/_index.md @@ -1,11 +1,11 @@ --- -title: ArangoGraphML -menuTitle: ArangoGraphML -weight: 125 +title: ArangoGraphML # Rename as well? +menuTitle: GraphML +weight: 20 description: >- Enterprise-ready, graph-powered machine learning as a cloud service or self-managed aliases: - - graphml + - arangographml --- Traditional Machine Learning (ML) overlooks the connections and relationships between data points, which is where graph machine learning excels. However, @@ -13,6 +13,56 @@ accessibility to GraphML has been limited to sizable enterprises equipped with specialized teams of data scientists. ArangoGraphML simplifies the utilization of GraphML, enabling a broader range of personas to extract profound insights from their data. +## Use cases + +GraphML capabilities of using more data outperform conventional deep learning +methods and **solve high-computational complexity graph problems**, such as: +- Drug discovery, repurposing, and predicting adverse effects. +- Personalized product/service recommendation. +- Supply chain and logistics. + +With GraphML, you can also **predict relationships and structures**, such as: +- Predict molecules for treating diseases (precision medicine). +- Predict fraudulent behavior, credit risk, purchase of product or services. +- Predict relationships among customers, accounts. + +ArangoDB uses well-known GraphML frameworks like +[Deep Graph Library](https://www.dgl.ai) +and [PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/) +and connects to these external machine learning libraries. When coupled to +ArangoDB, you are essentially integrating them with your graph dataset. + +#### Example: ArangoFlix + +ArangoFlix is a complete movie recommendation application that predicts missing +links between a user and the movies they have not watched yet. + +This [interactive tutorial](https://colab.research.google.com/github/arangodb/interactive_tutorials/blob/master/notebooks/Integrate_ArangoDB_with_PyG.ipynb) +demonstrates how to integrate ArangoDB with PyTorch Geometric to +build recommendation systems using Graph Neural Networks (GNNs). + +The full ArangoFlix demo website is accessible from the ArangoGraph Insights Platform, +the managed cloud for ArangoDB. You can open the demo website that connects to +your running database from the **Examples** tab of your deployment. + +{{< tip >}} +You can try out the ArangoGraph Insights Platform free of charge for 14 days. +Sign up at [dashboard.arangodb.cloud](https://dashboard.arangodb.cloud/home?utm_source=docs&utm_medium=cluster_pages&utm_campaign=docs_traffic). +{{< /tip >}} + +The ArangoFlix demo uses five different recommendation methods: +- Content-Based using AQL +- Collaborative Filtering using AQL +- Content-Based using ML +- Matrix Factorization +- Graph Neural Networks + +![ArangoFlix demo](../../images/data-science-arangoflix.png) + +The ArangoFlix website not only offers an example of how the user recommendations might +look like in real life, but it also provides information on a recommendation method, +an AQL query, a custom graph visualization for each movie, and more. + ## How GraphML works Graph machine learning leverages the inherent structure of graph data, where diff --git a/site/content/3.13/data-science/arangographml/deploy.md b/site/content/3.13/data-science/graphml/deploy.md similarity index 98% rename from site/content/3.13/data-science/arangographml/deploy.md rename to site/content/3.13/data-science/graphml/deploy.md index 0d62cb12f6..dccca0b59d 100644 --- a/site/content/3.13/data-science/arangographml/deploy.md +++ b/site/content/3.13/data-science/graphml/deploy.md @@ -5,6 +5,8 @@ weight: 5 description: >- You can deploy ArangoGraphML in your own Kubernetes cluster or use the managed cloud service that comes with a ready-to-go, pre-configured environment +aliases: + - ../arangographml/deploy --- ## Managed cloud service versus self-managed diff --git a/site/content/3.13/data-science/arangographml/getting-started.md b/site/content/3.13/data-science/graphml/getting-started.md similarity index 99% rename from site/content/3.13/data-science/arangographml/getting-started.md rename to site/content/3.13/data-science/graphml/getting-started.md index 6bd614167e..51b756d81d 100644 --- a/site/content/3.13/data-science/arangographml/getting-started.md +++ b/site/content/3.13/data-science/graphml/getting-started.md @@ -5,7 +5,8 @@ weight: 10 description: >- How to control all resources inside ArangoGraphML in a scriptable manner aliases: - - getting-started-with-arangographml + - ../arangographml/getting-started-with-arangographml + - ../arangographml/getting-started --- ArangoGraphML provides an easy-to-use & scalable interface to run Graph Machine Learning on ArangoDB Data. Since all of the orchestration and ML logic is managed by ArangoGraph, all that is typically required are JSON specifications outlining individual processes to solve an ML Task. If you are using the self-managed solution, additional configurations may be required. diff --git a/site/content/3.13/data-science/llm-knowledge-graphs.md b/site/content/3.13/data-science/hybrid-rag.md similarity index 73% rename from site/content/3.13/data-science/llm-knowledge-graphs.md rename to site/content/3.13/data-science/hybrid-rag.md index 80d8be9666..c11cdaa8eb 100644 --- a/site/content/3.13/data-science/llm-knowledge-graphs.md +++ b/site/content/3.13/data-science/hybrid-rag.md @@ -1,9 +1,13 @@ --- -title: Large Language Models (LLMs) and Knowledge Graphs -menuTitle: Large Language Models and Knowledge Graphs -weight: 133 +title: Graph-powered HybridRAG +menuTitle: HybridRAG +weight: 10 description: >- - Integrate large language models (LLMs) with knowledge graphs using ArangoDB + ArangoDB's HybridRAG combines graph-based retrieval augmented generation + (GraphRAG) with Large Language Models (LLMs) for turbocharged Gen AI solutions +aliases: + llm-knowledge-graphs +# TODO: Repurpose for GenAI --- Large language models (LLMs) and knowledge graphs are two prominent and contrasting concepts, each possessing unique characteristics and functionalities @@ -25,7 +29,17 @@ ArangoDB's unique capabilities and flexible integration of knowledge graphs and LLMs provide a powerful and efficient solution for anyone seeking to extract valuable insights from diverse datasets. -## Knowledge Graphs +The HybridRAG component of the Data Science Suite brings all the capabilities +together with an easy-to-use interface so you can make the knowledge accessible +to your organization. + +## HybridRAG + +ArangoDB's HybridRAG solution democratizes the creation and usage of knowledge +graphs with a unique combination of vector search, graphs, and LLMs in a +single product. + +### Knowledge Graphs A knowledge graph can be thought of as a dynamic and interconnected network of real-world entities and the intricate relationships that exist between them. @@ -48,7 +62,29 @@ the following tasks: ![ArangoDB Knowledge Graphs and LLMs](../../images/ArangoDB-knowledge-graphs-meets-llms.png) -## ArangoDB and LangChain +### Examples + +### Services + +#### Service A + +#### Service B + +### Interfaces + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. In the Platform UI, ... +{{< /tab >}} + +{{< tab "cURL" >}} +curl http://localhost:8529/gen-ai/ +{{< /tab >}} + +{{< /tabs >}} + +#### ArangoDB and LangChain [LangChain](https://www.langchain.com/) is a framework for developing applications powered by language models. @@ -62,7 +98,7 @@ data seamlessly via natural language, eliminating the need for query language design. By using LLM chat models such as OpenAI’s ChatGPT, you can "speak" to your data instead of querying it. -### Get started with ArangoDB QA chain +##### Get started with ArangoDB QA chain The [ArangoDB QA chain notebook](https://langchain-langchain.vercel.app/docs/use_cases/more/graph/graph_arangodb_qa.html) shows how to use LLMs to provide a natural language interface to an ArangoDB @@ -70,4 +106,4 @@ instance. Run the notebook directly in [Google Colab](https://colab.research.google.com/github/arangodb/interactive_tutorials/blob/master/notebooks/Langchain.ipynb). -See also other [machine learning interactive tutorials](https://github.com/arangodb/interactive_tutorials#machine-learning). \ No newline at end of file +See also other [machine learning interactive tutorials](https://github.com/arangodb/interactive_tutorials#machine-learning). From 3ef992fc379fdc35202bdf40753b8849d8d52d70 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Wed, 30 Apr 2025 10:17:23 +0200 Subject: [PATCH 2/7] Fix image --- site/content/3.13/data-science/_index.md | 3 ++- site/content/3.13/data-science/graphml/_index.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/site/content/3.13/data-science/_index.md b/site/content/3.13/data-science/_index.md index 7311f10dcb..b3158d8fc6 100644 --- a/site/content/3.13/data-science/_index.md +++ b/site/content/3.13/data-science/_index.md @@ -3,7 +3,8 @@ title: Data Science menuTitle: Data Science weight: 115 description: >- - ArangoDB lets you + ArangoDB's set of tools and technologies enables analytics, machine learning, + and GenAI applications powered by graph data aliases: - data-science/overview --- diff --git a/site/content/3.13/data-science/graphml/_index.md b/site/content/3.13/data-science/graphml/_index.md index 96590d719d..54d0bed905 100644 --- a/site/content/3.13/data-science/graphml/_index.md +++ b/site/content/3.13/data-science/graphml/_index.md @@ -57,7 +57,7 @@ The ArangoFlix demo uses five different recommendation methods: - Matrix Factorization - Graph Neural Networks -![ArangoFlix demo](../../images/data-science-arangoflix.png) +![ArangoFlix demo](../../../images/data-science-arangoflix.png) The ArangoFlix website not only offers an example of how the user recommendations might look like in real life, but it also provides information on a recommendation method, From 0f5743a0bf3f67e0f9715bbdddc1ae27e52d8743 Mon Sep 17 00:00:00 2001 From: Mohammad Dawas Date: Tue, 10 Jun 2025 15:15:59 +0300 Subject: [PATCH 3/7] adding natural language service documentation --- .../DEVELOPER_GUIDE.md | 332 ++++++++++++++++++ .../natural_language_service/USER_GUIDE.md | 231 ++++++++++++ 2 files changed, 563 insertions(+) create mode 100644 genai_docs/natural_language_service/DEVELOPER_GUIDE.md create mode 100644 genai_docs/natural_language_service/USER_GUIDE.md diff --git a/genai_docs/natural_language_service/DEVELOPER_GUIDE.md b/genai_docs/natural_language_service/DEVELOPER_GUIDE.md new file mode 100644 index 0000000000..c3bfce0642 --- /dev/null +++ b/genai_docs/natural_language_service/DEVELOPER_GUIDE.md @@ -0,0 +1,332 @@ +# Developer Guide for txt2aql + +This guide provides comprehensive instructions for developers working with the Natural Language to AQL Translation Service (txt2aql). + +## Table of Contents +- [Development Environment Setup](#development-environment-setup) +- [Project Structure](#project-structure) +- [Development Workflow](#development-workflow) + - [Local Development](#local-development) + - [Protobuf Code Generation](#code-generation) + - [Code Quality](#code-quality) + - [Testing](#testing) +- [LLM Provider Configuration](#llm-provider-configuration) +- [Deployment](#deployment) +- [CI Pipeline](#ci-pipeline) +- [Troubleshooting](#troubleshooting) + +## Development Environment Setup + +### Prerequisites +- Python 3.12+ +- Poetry for dependency management +- Docker +- ArangoDB instance +- One of the supported LLM providers: + - OpenAI API key + - Triton server + - Ollama + +### Initial Setup + +1. Clone the repository +```bash +git clone +cd natural-language-service +``` + +2. Install Poetry (if not already installed) +```bash +pipx install poetry +``` + +3. Install project dependencies +```bash +poetry install +``` +This should create a virtual environment inside the project and install all the necessary dependencies for the project plus the project package to your local environment. + +## Project Structure +Here is the structure of the main parts of the project: +``` +natural-language-service/ +├── txt2aql/ # Core service code +│ ├── server.py # gRPC server implementation +│ ├── service.py # Main service logic +│ ├── read_only_chain.py # LangChain implementation for read-only chain +│ └── llm_factory.py # LLM provider factory +├── proto/ # Protocol buffer definitions +├── tests/ # Test suite +│ ├── unit/ # Unit tests +│ └── integration/ # Integration tests +├── docs/ # Documentation +└── charts/ # Helm charts for deployment +``` + +## Development Workflow + +### Local Development + +#### Docker Compose File + +The `docker-compose.yml` file in this repository defines three main services for local development: + +- **python**: Runs the `txt2aql` application, exposing ports for gRPC APIs. It is built from the local source and configured with environment variables for database and LLM provider integration. +- **proxy**: Acts as a reverse proxy, routing external HTTP traffic to the appropriate backend service ports for easier access and local testing. +- **arangodb**: Provides a local ArangoDB instance with persistent storage and default credentials, used by the application for data storage and retrieval. Please note that this instance does not have data stored in it yet, so running queries against ArangoDB instance is not yet possible in dev environment. + +The file sets up networking and environment variables to ensure all services can communicate and persist data as needed. To launch the full stack locally, use: + +```bash +docker-compose up +``` + +This setup streamlines development, ensures consistent environments, and simplifies dependency management. + +### Code Generation + +Generate Protocol Buffer code: +```bash +./compile_protos.sh +``` + +### Code Quality + +#### Pre-commit Hooks + +Pre-commit hooks are automated checks that run before each commit to ensure code quality and consistency. They help catch issues early in the development process and maintain high code standards across the project. + +##### Installation + +The pre-commit package is included in the development dependencies. If you haven't already, install them with: + +```bash +poetry install --with dev +``` + +Install the pre-commit hooks into your local git repository: + +```bash +poetry run pre-commit install +``` + +##### Available Hooks + +The project uses several pre-commit hooks for quality control: + +1. **Code Formatting** + + - `isort`: Sorts Python imports alphabetically and separates them into sections + - `black`: Enforces consistent Python code formatting + +2. **Static Analysis** + + - `mypy`: Performs static type checking of Python code + - `flake8`: Checks for style guide enforcement and coding standards + +3. **Security** + + - `bandit`: Scans for common security issues in Python code (excludes tests and generated code) + +##### Best Practices + +1. Address all hook failures before pushing code +2. Don't bypass hooks unless absolutely necessary +3. Consider using VS Code extensions of these linting tools to get automated fixes on the fly. + +### Testing + +### Unit Tests + +Run unit tests: +```bash +poetry run pytest tests/unit/ +``` + +### Integration Tests + +So far there is no integration tests environment for local development. So these tests shold be executed in the CI pipeline. In this section, we are explaining the scripts used in preparing integration tests environment on the CI pipeline. + +#### Test Model Creation + +The service includes a script to create a minimal test model for Triton inference server testing. The model consists of: + +1. A simple ONNX model that implements an identity operation +2. Triton model configuration in protobuf text format +3. Proper directory structure required by Triton + +To create the test model: + +```bash +poetry run python scripts/tests/create_test_model.py +``` + +This creates: + +```plaintext +artifacts/ +└── minimal_model/ + ├── 1/ + │ └── model.onnx # Minimal ONNX model + └── config.pbtxt # Triton configuration +``` + +The generated model: + +- Accepts string input (single element) +- Returns string output (identity function) +- Uses ONNX Runtime as the backend +- Has no batching enabled + +You can use this as a template to create your own test models by modifying the input/output specifications and model operations in `create_test_model.py`. + +#### Create Test Database + +For testing purposes, the service includes a script to create a test database with sample data. The script: + +1. Connects to ArangoDB's system database +2. Creates a new test database +3. Sets up a test collection with indexed fields +4. Populates it with sample student data + +To create the test database: + +```bash +poetry run python scripts/tests/create_test_database.py +``` + +The script will: + +- Create a new database with the test database name +- Create a collection named "students" +- Add a persistent unique index on the "name" field +- Insert sample documents: + +```json +{"name": "jane", "age": 39} +{"name": "josh", "age": 18} +{"name": "judy", "age": 21} +``` + +This script is executed automatically inside the entrypoint-tests.sh script, so you don't need to run it manually. +Note: Ensure your ArangoDB instance is running and accessible before running this script. The script uses environment variable `ARANGODB_ENDPOINT` for the connection. + +#### Prepare Test Environment + +The `prepare_test_environment.py` script sets up a complete testing environment in Kubernetes with the following components: + +1. **MLflow Setup** + - Deploys MLflow artifact repository service for model storage + - Deploys MLflow tracking service for model registry + - Registers the test model ("minimal_model") created in the previous step + +2. **LLM Host (Triton) Setup** + - Deploys Triton Inference Server for model serving + - Resource configuration: + - Memory: 1-2Gi + - CPU: 100-200m + - Storage: 10-15Gi + +3. **Service Deployment** + - Deploys two instances of the Natural Language service: + - One using OpenAI for testing + - One using Triton with the test model + +Similar to the create_test_database.py script, the script is executed automatically inside the entrypoint-tests.sh script, so you don't need to run it manually. + +#### Environment Variables +The script also sets environment variables needed by the tests: +- `TRITON_HTTP_URL`: Triton server HTTP endpoint +- `TRITON_GRPC_URI`: Triton server gRPC endpoint +- `NL_SERVICE_OPENAI_URL`: OpenAI-backed service URL +- `NL_SERVICE_TRITON_URL`: Triton-backed service URL + +## LLM Provider Configuration + +### OpenAI Configuration + +- Default model: gpt-3.5-turbo +- Configurable temperature and retry settings +- API key required + +### Triton Configuration + +- Requires running Triton Inference Server +- Model must be loaded and available +- gRPC endpoint configuration required + +### Ollama Configuration + +- Local LLM deployment +- Requires running Ollama server +- Supports various open-source models + +Please note that Ollama is not meant for production use. + +## Deployment + +### Helm Chart Deployment + +The project includes a Helm chart that can be used to deploy the service. This helm chart defines the resources that will be created and used upon installation. + +Service installation must be done through GenAI service exclusively. Please check the grpc endpoint `CreateGraphRag`, which is accessible via http post request: `/v1/graphrag` +to install the service. + +All required parameters are defined in the helm chart's deployment.yaml file and labeled with keyword `required`. + +## CI Pipeline + +The project uses CircleCI for continuous integration and deployment. The pipeline consists of several workflows: + +### Main Workflows + +1. **python_ci**: Code quality checks + - `test`: Runs unit tests with pytest + - `lint`: Runs code quality checks (black, isort, mypy, flake8, bandit) + +2. **dev**: Runs on non-main branches + - Builds development Docker images + - Creates development Helm charts + - Deploys to development environment + - Runs integration tests + +3. **qa**: Runs on main branch + - Builds QA Docker images + - Creates QA Helm charts + - Deploys to both development and QA environments + - Runs integration tests + +### Key Features + +- Uses AWS ECR for Docker image storage +- Deploys Helm charts to S3 buckets +- Supports two environments: dev and qa. +- Includes integration tests with MLflow and Triton server +- Uses Poetry for Python dependency management + +### Environment Requirements + +The pipeline requires several context variables: +- `aws`: AWS credentials and configuration +- `agml-pypi`: Private PyPI repository credentials +- `LLM-KEYS`: OpenAI API keys for testing +- `ArangoML-CI-Jenkins`: CI/CD integration settings + +## Troubleshooting + +### Common Issues + +1. Database Connection Issues + - Verify ARANGODB_URL is accessible + - Check authentication credentials + - Ensure database exists and is accessible + +2. LLM Provider Issues + - Verify API credentials + - Check provider endpoint availability + - Validate model names and configurations + +3. gRPC/HTTP Connection Issues + - Check port availability (9090 for gRPC, 8080 for HTTP) + - Verify network/firewall settings + - Check SSL/TLS configuration if enabled diff --git a/genai_docs/natural_language_service/USER_GUIDE.md b/genai_docs/natural_language_service/USER_GUIDE.md new file mode 100644 index 0000000000..bf92cf1f3a --- /dev/null +++ b/genai_docs/natural_language_service/USER_GUIDE.md @@ -0,0 +1,231 @@ +# Natural Language to AQL Translation Service (txt2aql) + +## Overview +The Natural Language to AQL Translation Service is a powerful tool that allows you to interact with your ArangoDB database using natural language queries. It translates your questions and commands into AQL (ArangoDB Query Language), executes the queries, and provides responses in natural language. + +## Features +- Natural language to AQL query translation +- Support for multiple LLM providers (via OpenAI API or a self-hosted Triton Inference Server) +- RESTful and gRPC interfaces +- Health monitoring endpoints +- Flexible output formats (Natural Language, AQL, JSON) + +## Getting Started + +### Prerequisites +- ArangoDB instance +- OpenAI API key (if using OpenAI as provider) +- Triton URL and model name (if using Triton as provider) + + +### Configuration +The following environment variables are set at installation time and used at runtime: + +```bash +# Required Database Configuration +ARANGODB_NAME= +ARANGODB_USER= + +# LLM Provider Configuration +API_PROVIDER= # "openai" or "triton" + +# If using OpenAI +OPENAI_API_KEY= +OPENAI_MODEL= # Optional, defaults to GPT-4 +OPENAI_TEMPERATURE= # Optional +OPENAI_MAX_RETRIES= # Optional + +# If using Triton +TRITON_URL= +TRITON_MODEL= +TRITON_TIMEOUT= # Optional +``` + +### Starting the Service +To start the service, use GenAI service endpoint `CreateGraphRag`. Please refer to the documentation of GenAI service for more information on how to use it. + +### Required Parameters +These parameters must be provided in the install request sent to GenAI service. + +- `username`: Database username for authentication +- `db_name`: Name of the ArangoDB database +- `api_provider`: LLM provider selection (`openai`, `triton`) + +### Provider-Specific Required Parameters + +#### OpenAI Provider + +- `openai_api_key`: API key for OpenAI authentication +- `openai_model`: Model name (defaults to "gpt-3.5-turbo" if not specified) + +#### Triton Provider + +- `triton_url`: URL of the Triton inference server +- `triton_model`: Model name to use with Triton + + +## API Reference + +### REST Endpoints + +1. **Process Text** - Ask general questions to the LLM and get a natural language response. This endpoint does not query the database. +```bash +POST /v1/process_text +Content-Type: application/json + +{ + "input_text": "What are the advantages of graph databases?" +} +``` + +2. **Translate Query** - Convert natural language to AQL and query the database +```bash +POST /v1/translate_query +Content-Type: application/json + +{ + "input_text": "Find all users who are friends with John", + "options": { + "output_formats": ["NL", "AQL", "JSON"] + } +} +``` + + +3. **Health Check** - Monitor service health +```bash +GET /v1/health +``` + +### gRPC Endpoints + +The service also provides gRPC endpoints for more efficient communication: + +1. **Process Text** +```bash +grpcurl -plaintext -d '{"input_text": "Hello world"}' \ + localhost:9090 txt2aql.Txt2AqlService/ProcessText +``` + +2. **Translate Query** +```bash +grpcurl -plaintext -d '{ + "input_text": "Find all characters from House Stark", + "options": { + "output_formats": ["NL","AQL","JSON"] + } +}' localhost:9090 txt2aql.Txt2AqlService/TranslateQuery +``` + +3. **Health Check** +```bash +grpcurl -plaintext localhost:9090 txt2aql.Txt2AqlService/HealthCheck +``` + +## Output Formats + +The `translate_query` endpoint of the txt2aql service supports multiple output formats that can be specified in the `output_formats` field of your request. Each format serves a different purpose and can be used individually or in combination: + +### Natural Language (NL) + +- **Format identifier**: `"NL"` +- **Returns**: A human-readable explanation of the query results +- **Helpful for**: Understanding what the query found in plain English +- **Example**: + - **Input**: `Find all users who are friends with John` + - **Output**: `I found 3 users who are friends with John, including Alice, Bob, and Carol` + +### AQL Query (AQL) + +- **Format identifier**: `"AQL"` +- **Returns**: The generated ArangoDB Query Language (AQL) query +- **Useful for**: + - Debugging query translation + - Learning AQL syntax + - Modifying queries for reuse +- **Shows**: Exactly how your natural language was translated into database operations +- **Example**: + - **Input**: `Find all users who are friends with John` + - **Output**: `FOR u IN users FILTER u.friends ANY == 'John' RETURN u` + +### JSON Results (JSON) + +- **Format identifier**: `"JSON"` +- **Returns**: The raw query results in JSON format +- **Provides**: Direct access to the complete dataset +- **Ideal for**: + - Programmatic processing + - Data integration + - Custom formatting needs +- **Example**: + - **Input**: `Find all users who are friends with John` + - **Output**: `[{"name":"Alice","age":30},{"name":"Bob","age":25},{"name":"Carol","age":35}]` + +### Example Response + +```json +{ + "original_query": "Find all users who are friends with John", + "nl_response": "I found 3 users who are friends with John: Alice, Bob, and Carol", + "aql_query": "FOR u IN users FILTER u.friends ANY == 'John' RETURN u", + "aql_result": "[{\"name\":\"Alice\",\"age\":30},{\"name\":\"Bob\",\"age\":25},{\"name\":\"Carol\",\"age\":35}]" +} +``` + +### Usage Tips + +1. Request only the formats you need to minimize response size and processing time +2. Use `NL` for user interfaces, human consumption or when wrapped as an LLM-callable function (e.g. in LLM agent frameworks) +3. Use `AQL` for debugging and learning purposes +4. Use `JSON` for programmatic data processing such as API calls. + +### Default Behavior + +- If no output formats are specified, the service defaults to `NL` format only +- Multiple formats can be requested simultaneously +- Formats are processed efficiently, with results cached where possible + +## Error Handling + +The service provides clear error messages for common issues: + +- Invalid or missing environment variables +- Database connection failures +- Authentication errors +- Invalid query formats +- LLM provider errors + +Error responses include appropriate HTTP status codes and descriptive messages. + +## Best Practices + +1. Be specific in your queries to get more accurate translations +2. Use appropriate output formats based on your needs +3. Monitor the health endpoint for service status +4. Implement proper error handling in your client applications +5. Use connection pooling for better performance +6. Consider rate limiting for production deployments + +## Troubleshooting + +Common issues and solutions: + +1. **Connection Issues** + - Verify ARANGODB_ENDPOINT is accessible + - Check network/firewall settings + - Ensure proper authentication credentials + +2. **Query Translation Issues** + - Make queries more specific + - Check LLM provider configuration + - Verify database schema matches query context + - The quality of the generated AQL may vary depending on the LLM model used. + Therefore we recommend using an AQL-capable coding model (e.g. a frontier AQL-capable + LLM or a fine-tuned AQL-capable coding model) for better results. + +## Support + +For issues and feature requests, please refer to: +- GitHub Issues +- Documentation +- Community Forums From b862dc24de5b39896f96c04d368db518a70ce8e6 Mon Sep 17 00:00:00 2001 From: Mohammad Dawas Date: Tue, 10 Jun 2025 15:22:56 +0300 Subject: [PATCH 4/7] remove dev guide of NL service; was added by mistake --- .../DEVELOPER_GUIDE.md | 332 ------------------ 1 file changed, 332 deletions(-) delete mode 100644 genai_docs/natural_language_service/DEVELOPER_GUIDE.md diff --git a/genai_docs/natural_language_service/DEVELOPER_GUIDE.md b/genai_docs/natural_language_service/DEVELOPER_GUIDE.md deleted file mode 100644 index c3bfce0642..0000000000 --- a/genai_docs/natural_language_service/DEVELOPER_GUIDE.md +++ /dev/null @@ -1,332 +0,0 @@ -# Developer Guide for txt2aql - -This guide provides comprehensive instructions for developers working with the Natural Language to AQL Translation Service (txt2aql). - -## Table of Contents -- [Development Environment Setup](#development-environment-setup) -- [Project Structure](#project-structure) -- [Development Workflow](#development-workflow) - - [Local Development](#local-development) - - [Protobuf Code Generation](#code-generation) - - [Code Quality](#code-quality) - - [Testing](#testing) -- [LLM Provider Configuration](#llm-provider-configuration) -- [Deployment](#deployment) -- [CI Pipeline](#ci-pipeline) -- [Troubleshooting](#troubleshooting) - -## Development Environment Setup - -### Prerequisites -- Python 3.12+ -- Poetry for dependency management -- Docker -- ArangoDB instance -- One of the supported LLM providers: - - OpenAI API key - - Triton server - - Ollama - -### Initial Setup - -1. Clone the repository -```bash -git clone -cd natural-language-service -``` - -2. Install Poetry (if not already installed) -```bash -pipx install poetry -``` - -3. Install project dependencies -```bash -poetry install -``` -This should create a virtual environment inside the project and install all the necessary dependencies for the project plus the project package to your local environment. - -## Project Structure -Here is the structure of the main parts of the project: -``` -natural-language-service/ -├── txt2aql/ # Core service code -│ ├── server.py # gRPC server implementation -│ ├── service.py # Main service logic -│ ├── read_only_chain.py # LangChain implementation for read-only chain -│ └── llm_factory.py # LLM provider factory -├── proto/ # Protocol buffer definitions -├── tests/ # Test suite -│ ├── unit/ # Unit tests -│ └── integration/ # Integration tests -├── docs/ # Documentation -└── charts/ # Helm charts for deployment -``` - -## Development Workflow - -### Local Development - -#### Docker Compose File - -The `docker-compose.yml` file in this repository defines three main services for local development: - -- **python**: Runs the `txt2aql` application, exposing ports for gRPC APIs. It is built from the local source and configured with environment variables for database and LLM provider integration. -- **proxy**: Acts as a reverse proxy, routing external HTTP traffic to the appropriate backend service ports for easier access and local testing. -- **arangodb**: Provides a local ArangoDB instance with persistent storage and default credentials, used by the application for data storage and retrieval. Please note that this instance does not have data stored in it yet, so running queries against ArangoDB instance is not yet possible in dev environment. - -The file sets up networking and environment variables to ensure all services can communicate and persist data as needed. To launch the full stack locally, use: - -```bash -docker-compose up -``` - -This setup streamlines development, ensures consistent environments, and simplifies dependency management. - -### Code Generation - -Generate Protocol Buffer code: -```bash -./compile_protos.sh -``` - -### Code Quality - -#### Pre-commit Hooks - -Pre-commit hooks are automated checks that run before each commit to ensure code quality and consistency. They help catch issues early in the development process and maintain high code standards across the project. - -##### Installation - -The pre-commit package is included in the development dependencies. If you haven't already, install them with: - -```bash -poetry install --with dev -``` - -Install the pre-commit hooks into your local git repository: - -```bash -poetry run pre-commit install -``` - -##### Available Hooks - -The project uses several pre-commit hooks for quality control: - -1. **Code Formatting** - - - `isort`: Sorts Python imports alphabetically and separates them into sections - - `black`: Enforces consistent Python code formatting - -2. **Static Analysis** - - - `mypy`: Performs static type checking of Python code - - `flake8`: Checks for style guide enforcement and coding standards - -3. **Security** - - - `bandit`: Scans for common security issues in Python code (excludes tests and generated code) - -##### Best Practices - -1. Address all hook failures before pushing code -2. Don't bypass hooks unless absolutely necessary -3. Consider using VS Code extensions of these linting tools to get automated fixes on the fly. - -### Testing - -### Unit Tests - -Run unit tests: -```bash -poetry run pytest tests/unit/ -``` - -### Integration Tests - -So far there is no integration tests environment for local development. So these tests shold be executed in the CI pipeline. In this section, we are explaining the scripts used in preparing integration tests environment on the CI pipeline. - -#### Test Model Creation - -The service includes a script to create a minimal test model for Triton inference server testing. The model consists of: - -1. A simple ONNX model that implements an identity operation -2. Triton model configuration in protobuf text format -3. Proper directory structure required by Triton - -To create the test model: - -```bash -poetry run python scripts/tests/create_test_model.py -``` - -This creates: - -```plaintext -artifacts/ -└── minimal_model/ - ├── 1/ - │ └── model.onnx # Minimal ONNX model - └── config.pbtxt # Triton configuration -``` - -The generated model: - -- Accepts string input (single element) -- Returns string output (identity function) -- Uses ONNX Runtime as the backend -- Has no batching enabled - -You can use this as a template to create your own test models by modifying the input/output specifications and model operations in `create_test_model.py`. - -#### Create Test Database - -For testing purposes, the service includes a script to create a test database with sample data. The script: - -1. Connects to ArangoDB's system database -2. Creates a new test database -3. Sets up a test collection with indexed fields -4. Populates it with sample student data - -To create the test database: - -```bash -poetry run python scripts/tests/create_test_database.py -``` - -The script will: - -- Create a new database with the test database name -- Create a collection named "students" -- Add a persistent unique index on the "name" field -- Insert sample documents: - -```json -{"name": "jane", "age": 39} -{"name": "josh", "age": 18} -{"name": "judy", "age": 21} -``` - -This script is executed automatically inside the entrypoint-tests.sh script, so you don't need to run it manually. -Note: Ensure your ArangoDB instance is running and accessible before running this script. The script uses environment variable `ARANGODB_ENDPOINT` for the connection. - -#### Prepare Test Environment - -The `prepare_test_environment.py` script sets up a complete testing environment in Kubernetes with the following components: - -1. **MLflow Setup** - - Deploys MLflow artifact repository service for model storage - - Deploys MLflow tracking service for model registry - - Registers the test model ("minimal_model") created in the previous step - -2. **LLM Host (Triton) Setup** - - Deploys Triton Inference Server for model serving - - Resource configuration: - - Memory: 1-2Gi - - CPU: 100-200m - - Storage: 10-15Gi - -3. **Service Deployment** - - Deploys two instances of the Natural Language service: - - One using OpenAI for testing - - One using Triton with the test model - -Similar to the create_test_database.py script, the script is executed automatically inside the entrypoint-tests.sh script, so you don't need to run it manually. - -#### Environment Variables -The script also sets environment variables needed by the tests: -- `TRITON_HTTP_URL`: Triton server HTTP endpoint -- `TRITON_GRPC_URI`: Triton server gRPC endpoint -- `NL_SERVICE_OPENAI_URL`: OpenAI-backed service URL -- `NL_SERVICE_TRITON_URL`: Triton-backed service URL - -## LLM Provider Configuration - -### OpenAI Configuration - -- Default model: gpt-3.5-turbo -- Configurable temperature and retry settings -- API key required - -### Triton Configuration - -- Requires running Triton Inference Server -- Model must be loaded and available -- gRPC endpoint configuration required - -### Ollama Configuration - -- Local LLM deployment -- Requires running Ollama server -- Supports various open-source models - -Please note that Ollama is not meant for production use. - -## Deployment - -### Helm Chart Deployment - -The project includes a Helm chart that can be used to deploy the service. This helm chart defines the resources that will be created and used upon installation. - -Service installation must be done through GenAI service exclusively. Please check the grpc endpoint `CreateGraphRag`, which is accessible via http post request: `/v1/graphrag` -to install the service. - -All required parameters are defined in the helm chart's deployment.yaml file and labeled with keyword `required`. - -## CI Pipeline - -The project uses CircleCI for continuous integration and deployment. The pipeline consists of several workflows: - -### Main Workflows - -1. **python_ci**: Code quality checks - - `test`: Runs unit tests with pytest - - `lint`: Runs code quality checks (black, isort, mypy, flake8, bandit) - -2. **dev**: Runs on non-main branches - - Builds development Docker images - - Creates development Helm charts - - Deploys to development environment - - Runs integration tests - -3. **qa**: Runs on main branch - - Builds QA Docker images - - Creates QA Helm charts - - Deploys to both development and QA environments - - Runs integration tests - -### Key Features - -- Uses AWS ECR for Docker image storage -- Deploys Helm charts to S3 buckets -- Supports two environments: dev and qa. -- Includes integration tests with MLflow and Triton server -- Uses Poetry for Python dependency management - -### Environment Requirements - -The pipeline requires several context variables: -- `aws`: AWS credentials and configuration -- `agml-pypi`: Private PyPI repository credentials -- `LLM-KEYS`: OpenAI API keys for testing -- `ArangoML-CI-Jenkins`: CI/CD integration settings - -## Troubleshooting - -### Common Issues - -1. Database Connection Issues - - Verify ARANGODB_URL is accessible - - Check authentication credentials - - Ensure database exists and is accessible - -2. LLM Provider Issues - - Verify API credentials - - Check provider endpoint availability - - Validate model names and configurations - -3. gRPC/HTTP Connection Issues - - Check port availability (9090 for gRPC, 8080 for HTTP) - - Verify network/firewall settings - - Check SSL/TLS configuration if enabled From 430efc09bd16ed0828b2ef5d2706ef996f5b2bbc Mon Sep 17 00:00:00 2001 From: sachinsharma9780 Date: Tue, 10 Jun 2025 17:23:40 +0200 Subject: [PATCH 5/7] add user-facing-documentation for ragloader --- genai_docs/RagLoader/USER_GUIDE.md | 219 +++++++++++++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 genai_docs/RagLoader/USER_GUIDE.md diff --git a/genai_docs/RagLoader/USER_GUIDE.md b/genai_docs/RagLoader/USER_GUIDE.md new file mode 100644 index 0000000000..73b6506ebb --- /dev/null +++ b/genai_docs/RagLoader/USER_GUIDE.md @@ -0,0 +1,219 @@ +# RagLoader User Guide + +## Overview + +The RagLoader service helps you transform your text document into knowledge graph, making it easier to analyze and understand complex information. It works with individual text files, supporting plain text format with UTF-8 encoding or markdown files. + +The Loader takes your text, analyzes it using the configured language model, and creates a structured knowledge graph. This graph is then imported into your ArangoDB database, where you can query and analyze the relationships between different concepts in your document with our RagRetriever service. + + +## How ArangoDB Collections looks after Import Process: + +The RagLoader creates several collections in ArangoDB to store different aspects of your knowledge graph. Here's a detailed explanation of each collection: + +### Documents Collection +- **Purpose**: Stores the original text document that were processed +- **Key Fields**: + - `_key`: Unique identifier for the document + - `content`: The full text content of the document +- **Usage**: Acts as the root level container for all document-related data + +### Chunks Collection +- **Purpose**: Stores text chunks extracted from documents for better processing and analysis +- **Key Fields**: + - `_key`: Unique identifier for the chunk + - `content`: The text content of the chunk + - `tokens`: Number of tokens in the chunk + - `chunk_order_index`: Position of the chunk in the original document +- **Usage**: Enables granular analysis of document content and maintains document structure + +### Entities Collection +- **Purpose**: Stores entities extracted from the text, such as persons, organizations, concepts, etc. +- **Key Fields**: + - `_key`: Unique identifier for the entity + - `entity_name`: Name of the entity + - `entity_type`: Type of entity (e.g., person, organization) + - `description`: Description of the entity + - `embedding`: Vector representation of the entity for similarity search + - `clusters`: Community clusters the entity belongs to +- **Usage**: Enables entity-based querying and semantic search + +### Communities Collection +- **Purpose**: Stores thematic clusters of related entities that form meaningful communities within your documents. Each community represents a cohesive group of concepts, characters, or themes that are closely related and interact with each other. These communities help identify and analyze the main narrative threads, character relationships, and thematic elements in your documents. +- **Key Fields**: + - `_key`: Unique identifier for the community + - `title`: Cluster ID to which this community belongs to + - `report_string`: A detailed markdown-formatted analysis that explains the community's theme, key relationships, and significance. This includes sections on main characters, their roles, relationships, and the impact of key events or locations. + - `report_json`: Structured data containing: + - `title`: The main theme or focus of the community + - `summary`: A concise overview of the community's central narrative + - `rating`: A numerical score indicating the community's significance (higher the better) + - `rating_explanation`: Justification for the rating + - `findings`: An array of detailed analyses, each containing a summary and explanation of key aspects + - `level`: The hierarchical level of the community (e.g., 1 for top-level communities) + - `occurrence`: A normalized score (ranging from 0 to 1) showing the relative frequency with which this community is mentioned or identified throughout your documents. A value close to 1 means this community is very common in your data and a value near 0 means it is rare. + - `sub_communities`: References to more specific sub-communities that are part of this larger community +- **Usage**: Enables you to: + - Identify and analyze major narrative threads and themes + - Understand complex relationships between characters and concepts + - Track the significance and impact of different story elements + - Navigate through hierarchical relationships between themes + - Discover patterns and recurring elements in your documents + +### Relations Collection +- **Purpose**: Stores relationships between different nodes in the graph +- **Key Fields**: + - `_from`: Source node reference + - `_to`: Target node reference + - `type`: Type of relationship (e.g., "PART_OF", "MENTIONED_IN", "RELATED_TO", "IN_COMMUNITY") + - Additional metadata depending on relationship type (Entity to Entity): + - `weight`: Relationship strength (higher the better) + - `description`: Description of the relationship + - `source_id`: Source of the relationship + - `order`: Order of the relationship +- **Usage**: Enables traversal and analysis of relationships between different elements + +### Relationship Types +The system creates several types of relationships between nodes: + +1. **PART_OF**: Links chunks to their parent documents +2. **MENTIONED_IN**: Connects entities to the chunks where they are mentioned +3. **RELATED_TO**: Shows relationships between different entities +4. **IN_COMMUNITY**: Associates entities with their community groups + +### Vector Search Capabilities +The system automatically creates vector indexes on the `embedding` field in the Entities collection, enabling: +- Semantic similarity search +- Nearest neighbor queries +- Efficient vector-based retrieval + +## Available Deployment Options: + +You can choose between two deployment options based on your needs: + +1. If you're working in an air-gapped environment or need to keep your data private, you can use the private LLM mode with Triton Inference Server. This option allows you to run the service completely within your own infrastructure. The Triton Inference Server is a crucial component when running in private LLM mode. It serves as the backbone for running your language (LLM) and embedding models on youe own machines, ensuring your data never leaves your infrastructure. The server handles all the complex model operations, from processing text to generating embeddings, and provides both HTTP and gRPC interfaces for communication. + +2. Alternatively, if you prefer a simpler setup and don't have specific privacy requirements, you can use the public LLM mode. This option connects to cloud-based services like OpenAI's models via the OpenAI API or a large array of models (Gemini, Anthropic, publicly hosted open-source models, etc.) via the OpenRouter option. + + +### How to install RagLoader Service + +As mentioned RagLoader service can be configured to use either Triton Inference Server (for private LLM deployments) or OpenAI / OpenRouter (for public LLM deployments). +To start the service, use GenAI service endpoint `/v1/graphragimporter`. Please refer to the documentation of GenAI service for more information on how to use it. +Here are the configuration options for all three options: + +#### Option 1: Using Triton Inference Server (Private LLM) + +First setup and install LLM-Host service with LLM and embedding models of your choice. The setup will use Triton Inference Server and mlflow at the backend. Please refer to below documentation for more dtetail: +// @docs-team please insert reference to GenAI/Triton documentation here + +Once the LLM-host service is installed and running successfully, then you can start the loader service using the below reference: + +```json +{ + "env": { + "username": "your_username", + "db_name": "your_database_name", + "api_provider": "triton", + "triton_url": "your-arangodb-llm-host-url", + "triton_model": "mistral-nemo-instruct" + }, +} +``` + +- `username`: ArangoDB database user with permissions to create and modify collections +- `db_name`: Name of the ArangoDB database where the knowledge graph will be stored +- `api_provider`: Specifies which LLM provider to use +- `triton_url`: URL of your Triton Inference Server instance. This should be the URL where your LLM-host service is running +- `triton_model`: Name of the LLM model to use for text processing + +#### Using OpenAI + +```json +{ + "env": { + "openai_api_key": "your_openai_api_key", + "username": "your_username", + "db_name": "your_database_name", + "api_provider": "openai" + }, +} +``` + +- `username`: ArangoDB database user with permissions to create and modify collections +- `db_name`: Name of the ArangoDB database where the knowledge graph will be stored +- `api_provider`: Specifies which LLM provider to use +- `openai_api_key`: Your OpenAI API key + +Note: By default for openai api we use gpt-4o-mini and text-embedding-3-small models as LLM and embedding model respectively. + + +### Using OpenRouter (Gemini, Anthropic, etc.) + +OpenRouter makes it possible to connect to a huge array of LLM API providers, including non-OpenAI LLMs like Gemini Flash, Anthropic Claude and publicly hosted open-source models. + +When using the OpenRouter option, the LLM responses are served via OpenRouter while OpenAI is used for the embedding model. + +```json + { + "env": { + "db_name": "your_database_name", + "username": "your_username", + "api_provider": "openrouter", + "openai_api_key": "your_openai_api_key", + "openrouter_api_key": "your_openrouter_api_key", + "openrouter_model": "mistralai/mistral-nemo" // Specify a model here + }, + } +``` + +- `username`: ArangoDB database user with permissions to access collections +- `db_name`: Name of the ArangoDB database where the knowledge graph is stored +- `api_provider`: Specifies which LLM provider to use +- `openai_api_key`: Your OpenAI API key (for the embedding model) +- `openrouter_api_key`: Your OpenRouter API key (for the LLM) +- `openrouter_model`: Desired LLM (optional; default is `mistral-nemo`) + +> **Note** +> When using OpenRouter, we default to `mistral-nemo` for generation (via OpenRouter) and `text-embedding-3-small` for embeddings (via OpenAI). +## Building Knowledge Graphs + +Once service is installed successfully, you can follow the following steps to send an input file to the loader service: + +1. Prepare your text document for processing (text format with UTF-8 encoding or markdown files) + +2. Send the document to the RagLoader service using HTTP: + ```bash + # Base64 encode your document + base64_content=$(base64 -i your_document.txt) + + # Send to the Loader service + curl -X POST /v1/import \ + -H "Content-Type: application/json" \ + -d '{ + "file_content": "'$base64_content'", + "file_name": "your_document.txt" + }' + ``` + + Replace the following placeholders: + - ``: Your ArangoDB Platform URL + - ``: The URL postfix configured in your deployment + + + The service will: + - Process the document using the configured LLM model + - Generate embeddings using the embedding model + - Build a knowledge graph + - Import the graph into your ArangoDB database + + +### Verifying the Import + +You can verify that the import was successful by checking your ArangoDB database: + +1. Connect to your ArangoDB instance +2. Navigate to the specified database +3. Verify that the following collections exist: + - `knowledge_graph_vertices`: Contains the nodes of the knowledge graph i.e. documents, chunks, communities, and entities. + - `knowledge_graph_edges`: Contains the relationships between nodes i.e. relations. From 5685e2351ac5fc4c2c14f2031b2a60e7928fa8e6 Mon Sep 17 00:00:00 2001 From: sachinsharma9780 Date: Tue, 10 Jun 2025 17:23:59 +0200 Subject: [PATCH 6/7] add user-facing-documentation for ragretriever --- genai_docs/RagRetriever/USER_GUIDE.md | 196 ++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 genai_docs/RagRetriever/USER_GUIDE.md diff --git a/genai_docs/RagRetriever/USER_GUIDE.md b/genai_docs/RagRetriever/USER_GUIDE.md new file mode 100644 index 0000000000..5a11fb8b9c --- /dev/null +++ b/genai_docs/RagRetriever/USER_GUIDE.md @@ -0,0 +1,196 @@ +# RagRetriever User Guide + +## Summary + +RagRetriever is a powerful service that enables intelligent search and retrieval from knowledge graphs created by GraphRAG Importer. It offers two distinct search methods: + +- **Global Search**: Analyzes entire document to identify themes and patterns, perfect for high-level insights and comprehensive summaries. +- **Local Search**: Focuses on specific entities and their relationships, ideal for detailed queries about particular concepts. + +The service supports both private (Triton Inference Server) and public (OpenAI) LLM deployments, making it flexible for various security and infrastructure requirements. With simple HTTP endpoints, you can easily query your knowledge graph and get contextually relevant responses. + +Key features: +- Dual search methods for different query types +- Support for both private and public LLM deployments +- Simple REST API interface +- Integration with ArangoDB knowledge graphs +- Configurable community hierarchy levels + +## Overview + +The RagRetriever service enables intelligent search and retrieval of information from your knowledge graph. It provides two powerful search methods - Global Search and Local Search - that leverage the structured knowledge graph created by the GraphRAG Importer to deliver accurate and contextually relevant responses to your natural language queries. + +## Search Methods + +### Global Search + +Global Search is designed for queries that require understanding and aggregation of information across your entire document. It's particularly effective for questions about overall themes, patterns, or high-level insights in your data. + +#### How Global Search Works + +1. **Community-Based Analysis**: Uses pre-generated community reports from your knowledge graph to understand the overall structure and themes of your data +2. **Map-Reduce Processing**: + - **Map Stage**: Processes community reports in parallel, generating intermediate responses with rated points + - **Reduce Stage**: Aggregates the most important points to create a comprehensive final response + +#### Best Use Cases +- "What are the main themes in the dataset?" +- "Summarize the key findings across all documents" +- "What are the most important concepts discussed?" + +### Local Search + +Local Search focuses on specific entities and their relationships within your knowledge graph. It's ideal for detailed queries about particular concepts, entities, or relationships. + +#### How Local Search Works + +1. **Entity Identification**: Identifies relevant entities from the knowledge graph based on the query +2. **Context Gathering**: Collects: + - Related text chunks from original documents + - Connected entities and their strongest relationships + - Entity descriptions and attributes + - Context from the community each entity belongs to +3. **Prioritized Response**: Generates a response using the most relevant gathered information + +#### Best Use Cases +- "What are the properties of [specific entity]?" +- "How is [entity A] related to [entity B]?" +- "What are the key details about [specific concept]?" + +## How to install RagRetriever Service + +The RagRetriever service can be configured to use either Triton Inference Server (for private LLM deployments) or OpenAI / OpenRouter (for public LLM deployments). +To start the service, use GenAI service endpoint `/v1/graphragretriever`. Please refer to the documentation of GenAI service for more information on how to use it. +Here are the configuration options for all 3 options: + +### Using Triton Inference Server (Private LLM) + +First setup and install LLM-Host service with LLM and embedding models of your choice. The setup will use Triton Inference Server and mlflow at the backend. Please refer to below documentation for more detail: +// @docs-team please insert reference to GenAI/Triton documentation here + +Once the LLM-host service is installed and running successfully, then you can start the retriever service using the below reference: + +```json +{ + "env": { + "username": "your_username", + "db_name": "your_database_name", + "api_provider": "triton", + "triton_url": "your-arangodb-llm-host-url", + "triton_model": "mistral-nemo-instruct" + }, +} +``` + +- `username`: ArangoDB database user with permissions to access collections +- `db_name`: Name of the ArangoDB database where the knowledge graph is stored +- `api_provider`: Specifies which LLM provider to use +- `triton_url`: URL of your Triton Inference Server instance. This should be the URL where your LLM-host service is running +- `triton_model`: Name of the LLM model to use for text processing + +### Using OpenAI + +```json +{ + "env": { + "openai_api_key": "your_openai_api_key", + "username": "your_username", + "db_name": "your_database_name", + "api_provider": "openai" + }, +} +``` + +- `username`: ArangoDB database user with permissions to access collections +- `db_name`: Name of the ArangoDB database where the knowledge graph is stored +- `api_provider`: Specifies which LLM provider to use +- `openai_api_key`: Your OpenAI API key + +Note: By default for OpenAI API, we use gpt-4-mini and text-embedding-3-small models as LLM and embedding model respectively. +### Using OpenRouter (Gemini, Anthropic, etc.) + +OpenRouter makes it possible to connect to a huge array of LLM API providers, including non-OpenAI LLMs like Gemini Flash, Anthropic Claude and publicly hosted open-source models. + +When using the OpenRouter option, the LLM responses are served via OpenRouter while OpenAI is used for the embedding model. + +```json + { + "env": { + "db_name": "your_database_name", + "username": "your_username", + "api_provider": "openrouter", + "openai_api_key": "your_openai_api_key", + "openrouter_api_key": "your_openrouter_api_key", + "openrouter_model": "mistralai/mistral-nemo" // Specify a model here + }, + } +``` + +- `username`: ArangoDB database user with permissions to access collections +- `db_name`: Name of the ArangoDB database where the knowledge graph is stored +- `api_provider`: Specifies which LLM provider to use +- `openai_api_key`: Your OpenAI API key (for the embedding model) +- `openrouter_api_key`: Your OpenRouter API key (for the LLM) +- `openrouter_model`: Desired LLM (optional; default is `mistral-nemo`) + +> **Note** +> When using OpenRouter, we default to `mistral-nemo` for generation (via OpenRouter) and `text-embedding-3-small` for embeddings (via OpenAI). +## Using the Retriever Service + +### Executing Queries + +After the retriever service is installed successfully. You can interact with the retriever service using the following HTTP endpoint: + +#### Local Search + +```bash +curl -X POST /v1/graphrag-query \ + -H "Content-Type: application/json" \ + -d '{ + "query": "What is the AR3 Drone?", + "query_type": 2, + "provider": 0 + }' +``` + +#### Global Search + +```bash +curl -X POST /v1/graphrag-query \ + -H "Content-Type: application/json" \ + -d '{ + "query": "What is the AR3 Drone?", + "level": 1, + "query_type": 1, + "provider": 0 + }' +``` + +The request parameters are: +- `query`: Your search query text +- `level`: The community hierarchy level to use for the search (1 for top-level communities) +- `query_type`: The type of search to perform + - `1`: Global Search + - `2`: Local Search +- `provider`: The LLM provider to use + - `0`: OpenAI (or OpenRouter) + - `1`: Triton + +### Health Check + +Monitor the service health: +```bash +GET /v1/health +``` + +## Best Practices + +1. **Choose the Right Search Method**: + - Use Global Search for broad, thematic queries + - Use Local Search for specific entity or relationship queries + + +2. **Performance Considerations**: + - Global Search may take longer due to its map-reduce process + - Local Search is typically faster for concrete queries + From f098711d7eefdc852361c4672421de7f5d7e2497 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Thu, 12 Jun 2025 15:15:59 +0200 Subject: [PATCH 7/7] WIP: Add platform overview content from #671 --- site/content/3.13/components/platform.md | 71 ++++++++++++++++++++++++ site/content/3.13/deploy/_index.md | 9 +++ 2 files changed, 80 insertions(+) create mode 100644 site/content/3.13/components/platform.md diff --git a/site/content/3.13/components/platform.md b/site/content/3.13/components/platform.md new file mode 100644 index 0000000000..6b19dec493 --- /dev/null +++ b/site/content/3.13/components/platform.md @@ -0,0 +1,71 @@ +--- +title: The ArangoDB Platform +menuTitle: Platform +weight: 169 +description: >- + The ArangoDB Platform brings everything ArangoDB offers together to a single + solution that you can deploy on-prem or use as a managed service +--- +The ArangoDB Platform is a technical infrastructure that acts as the umbrella +for hosting the entire ArangoDB offering of products. The Platform makes it easy +to deploy and operate the core ArangoDB database system along with any additional +ArangoDB products for machine learning, data explorations, and more. You can +run it on-premise or in the cloud yourself on top of Kubernetes, as well as use +ArangoDB's managed service, the [ArangoGraph Insights Platform](../arangograph/_index.md) +to access all of the platform features. + +## Requirements for self-hosting + +- **Kubernetes**: Orchestrates the selected services that comprise the + ArangoDB Platform, running them in containers for safety and scalability. +- **Licenses**: If you want to use any paid features, you need to purchase the + respective packages. + +## Products available in the ArangoDB Platform + +- **Core database system**: The ArangoDB graph database system for storing + interconnected data. You can use the free Community Edition or the commercial + Enterprise Edition. +- **Graph visualizer**: A web-based tool for exploring your graph data with an + intuitive interface and sophisticated querying capabilities. +- **Data-science suite**: A set of paid machine learning services, APIs, and + user interfaces that are available as a package as well as individual products. + - **Vector embeddings**: You can train machine learning models for later use + in vector search in conjunction with the core database system's `vector` + index type. It allows you to find similar items in your dataset. + - **GraphRAG solutions**: Leverage ArangoDB's Graph, Document, Key-Value, + Full-Text Search, and Vector Search features to streamline knowledge + extraction and retrieval. + - **Txt2AQL**: Unlock natural language querying with a service that converts + user input into ArangoDB Query Language (AQL), powered by fine-tuned + private or public LLMs. + - **GraphRAG Importer**: Extract entities and relationships from large + text-based files, converting unstructured data into a knowledge graph + stored in ArangoDB. + - **GraphRAG Retriever**: Perform semantic similarity searches or aggregate + insights from graph communities with global and local queries. + - **GraphML**: A turnkey solution for graph machine learning for prediction + use cases such as fraud detection, supply chain, healthcare, retail, and + cyber security. + - **Graph Analytics**: A suite of graph algorithms including PageRank, + community detection, and centrality measures with support for GPU + acceleration thanks to Nvidia cuGraph. + - **Jupyter notebooks**: Run a Jupyter kernel in the platform for hosting + interactive notebooks for experimentation and development of applications + that use ArangoDB as their backend. + + + +## Get started with the ArangoDB Platform + +### Use the ArangoDB Platform as a managed service + + + +### Self-host the ArangoDB Platform + + + +## Interfaces + + \ No newline at end of file diff --git a/site/content/3.13/deploy/_index.md b/site/content/3.13/deploy/_index.md index 5a6de1a8d7..687d709c4e 100644 --- a/site/content/3.13/deploy/_index.md +++ b/site/content/3.13/deploy/_index.md @@ -45,6 +45,15 @@ on a single DB-Server node for better performance and with transactional guarantees similar to a single server deployment. OneShard is primarily intended for multi-tenant use cases. +### ArangoDB Platform + +The ArangoDB Platform is the umbrella for deploying and operating the entire +ArangoDB product offering with a unified interface in a Kubernetes cluster. +It is offered for self-hosting on-prem or in the cloud and as a managed service, +superseding the ArangoGraph Insights Platform. + +See [The ArangoDB Platform](../components/platform.md) for details. + ## How to deploy There are different ways to set up and operate ArangoDB.