From 0ad0a034b01a8c5c0c8ea439cab894d0612c8a3e Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Wed, 30 Apr 2025 10:08:19 +0200 Subject: [PATCH 01/16] 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 02/16] 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 03/16] 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 04/16] 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 05/16] 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 06/16] 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 07/16] 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. From 5b12ac5a315a432f74e8bcf3f092391920c38c83 Mon Sep 17 00:00:00 2001 From: maxkernbach Date: Wed, 18 Jun 2025 17:24:31 +0200 Subject: [PATCH 08/16] add user-facing-documentation for genai --- genai_docs/GenAI/USER_FACING_DOCUMENTATION.md | 180 ++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 genai_docs/GenAI/USER_FACING_DOCUMENTATION.md diff --git a/genai_docs/GenAI/USER_FACING_DOCUMENTATION.md b/genai_docs/GenAI/USER_FACING_DOCUMENTATION.md new file mode 100644 index 0000000000..433e4bd932 --- /dev/null +++ b/genai_docs/GenAI/USER_FACING_DOCUMENTATION.md @@ -0,0 +1,180 @@ +# GenAI-Service + +## Description + +The GenAI orchestrator service is a service that is able to install, manage, and run AI-based services in your Kubernetes cluster. + +The basic operations are: +- Install a service +- Uninstall a service +- Get the status of a service + +Each unique service does have its own API endpoint for the deployment. + +**Endpoint LLM Host:** +`https://:8529/gen-ai/v1/llmhost` + +While they have their own unique endpoint, all services share the same creation request body and the same response body structure. While the env field is used to define the service specific parameters, like e.g. the model name to use for a llm host service, the labels can be used to filter and identify the services in the platform. All services do support the 'profiles' field, which can be used to define the profile to use for the service. One use case is defining a GPU profile that enables the service to run an LLM on GPU resources. + +## Examples + +### LLM Host Service Creation Request Body + +```json +{ + "env": { + "model_name": "" + } +} +``` + +### Using Labels in Creation Request Body + +```json +{ + "env": { + "model_name": "" + }, + "labels": { + "key1": "value1", + "key2": "value2" + } +} +``` + +**Note:** Labels are optional. Labels can be used to filter and identify services in the platform. If you want to use labels, define them as a key-value pair in the `labels` within the `env` field. + +### Using Profiles in Creation Request Body + +```json +{ + "env": { + "model_name": "", + "profiles": "gpu,internal" + } +} +``` + +**Note:** The `profiles` field is optional. If it is not set, the service will be created with the default profile. Profiles must be present and created in the platform before they can be used. If you want to use profiles, define them as a comma-separated string in the `profiles` within the `env` field. + +The service specific required parameters for the deployment are defined in the corresponding service documentation. + +## Obtaining a Bearer Token + +Before you can authenticate with the GenAI service, you need to obtain a Bearer token. You can generate this token using the ArangoDB authentication API: + +```bash +curl -X POST https://:8529/_open/auth \ + -d '{"username": "your-username", "password": "your-password"}' +``` + +This will return a JWT token that you can use as your Bearer token. For more details about ArangoDB authentication and JWT tokens, see the [ArangoDB Authentication Documentation](https://docs.arangodb.com/stable/develop/http-api/authentication/#jwt-user-tokens). + +## Complete Service Lifecycle Example + +Here's a complete example showing how to install, monitor, and uninstall a RAGLoader service: + +### Step 1: Install the Service + +```bash +curl -X POST https://:8529/gen-ai/v1/graphragimporter \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "env": { + "username": "", + "db_name": "", + "api_provider": "", + "triton_url": "", + "triton_model": "" + } + }' +``` + +**Response:** +```json +{ + "serviceInfo": { + "serviceId": "arangodb-graphrag-importer-of1ml", + "description": "Install complete", + "status": "DEPLOYED", + "namespace": "arangodb-platform-dev" + } +} +``` + +### Step 2: Check Service Status + +```bash +curl -X GET https://:8529/gen-ai/v1/service/arangodb-graphrag-importer-of1ml \ + -H "Authorization: Bearer " +``` + +**Response:** +```json +{ + "serviceInfo": { + "serviceId": "arangodb-graphrag-importer-of1ml", + "description": "Install complete", + "status": "DEPLOYED", + "namespace": "arangodb-platform-dev" + } +} +``` + +### Step 3: Uninstall the Service + +```bash +curl -X DELETE https://:8529/gen-ai/v1/service/arangodb-graphrag-importer-of1ml \ + -H "Authorization: Bearer " +``` + +**Response:** +```json +{ + "serviceInfo": { + "serviceId": "arangodb-graphrag-importer-of1ml", + "description": "Uninstall complete", + "status": "UNINSTALLED", + "namespace": "arangodb-platform-dev" + } +} +``` + +**Notes:** + +- **Service ID**: The `serviceId` from Step 1's response (`arangodb-graphrag-importer-of1ml`) is used in Steps 2 and 3 +- **Authentication**: All requests use the same Bearer token in the `Authorization` header + +### Customizing the Example + +Replace the following values with your actual configuration: +- `` - Your database username +- `` - Target database name +- `` - Your API provider (e.g., "triton") +- `` - Your LLM host service URL +- `` - Your Triton model name (e.g., "mistral-nemo-instruct") +- `` - Your authentication token + +## Service Configuration + +The GenAI orchestrator service is **started by default**. + +It will be available at the following URL: +`https://:8529/gen-ai/v1/service` + +### Health Check + +To test whether the service is running, you can use the following snippet: + +```bash +curl -X GET https://:8529/gen-ai/v1/health +``` + +Expected output on success: `{"status":"OK"}` + +**Note:** Keep in mind that this request requires a valid Bearer token. Without a valid Bearer token, the request will fail. + +## API Reference + +For detailed API documentation, visit: [GenAI-Service API Reference](https://arangoml.github.io/platform-dss-api/GenAI-Service/proto/index.html) \ No newline at end of file From 70779227607405844058a92252bf5af0556336b2 Mon Sep 17 00:00:00 2001 From: maxkernbach Date: Wed, 18 Jun 2025 17:24:59 +0200 Subject: [PATCH 09/16] add user-facing-documentation for arangodb-mlflow --- .../USER_FACING_DOCUMENTATION.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 genai_docs/arangodb-mlflow/USER_FACING_DOCUMENTATION.md diff --git a/genai_docs/arangodb-mlflow/USER_FACING_DOCUMENTATION.md b/genai_docs/arangodb-mlflow/USER_FACING_DOCUMENTATION.md new file mode 100644 index 0000000000..b25ec4a74e --- /dev/null +++ b/genai_docs/arangodb-mlflow/USER_FACING_DOCUMENTATION.md @@ -0,0 +1,122 @@ +# ArangoDB-MLflow-Service + +## Overview + +The ArangoDB MLflow service is a service that hosts the official MLflow application in your Kubernetes cluster and connects it automatically to the ArangoDB environment, e.g. for registering the LLM to be self-hosted and used by services requiring LLMs (natural-language-service, RAGLoader, RAGRetriever). + +MLflow is an open-source platform, purpose-built to assist machine learning practitioners and teams in handling the complexities of the machine learning process. It focuses on the full lifecycle for machine learning projects, ensuring that each phase is manageable, traceable, and reproducible. + +The main purpose of our MLflow integration is to provide a seamless experience for users to manage their machine learning models and experiments within the ArangoDB environment. For example, any spawned LLM host service will automatically be linked to the MLflow service and will be able to fetch any registered model from the MLflow model registry. + +**Note:** The detailed instructions about how to organize the format of a model for the dedicated LLM host service can be found in their respective documentation. + +## Core Components + +MLflow consists of the following core components: + +- **Model Registry**: A centralized model store, set of APIs, and UI to collaboratively manage the full lifecycle of an MLflow Model, including model lineage, versioning, stage transitions, and annotations. + +- **Experiment Tracking**: Provides an API and UI for logging parameters, code versions, metrics, and artifacts during the ML process, allowing for comparison of multiple runs across different users. + +- **Model Packaging**: Offers a standard format for packaging models from any framework. + +- **Serving**: Facilitates the deployment of models to various platforms. Within the ArangoDB environment, this enables the integration with services that utilize self-hosted LLMs. + +- **Evaluation**: Provides tools for in-depth model analysis, facilitating objective model comparison. + +- **Observability**: Ensures that the ML lifecycle is traceable and reproducible through various metrics and logs. + +## Getting Started + +The ArangoDB MLflow service is **started by default**. + +It will be automatically spawned and available at the following URL: + +``` +https://:8529/mlflow/ +``` + +You can interact with the ArangoDB MLflow service in two ways: +- **Programmatically**: Using the official MLflow client +- **Web Interface**: Directly through your browser at the URL above + +To use the programmatic API, please use the **official MLflow client**. + +**Note:** The ArangoDB MLflow service requires authentication. You need a valid Bearer token to access the service. + +#### Obtaining a Bearer Token + +Before you can authenticate with the MLflow service, you need to obtain a Bearer token. You can generate this token using the ArangoDB authentication API: + +```bash +curl -X POST https://:8529/_open/auth \ + -d '{"username": "your-username", "password": "your-password"}' +``` + +This will return a JWT token that you can use as your Bearer token. For more details about ArangoDB authentication and JWT tokens, see the [ArangoDB Authentication Documentation](https://docs.arangodb.com/stable/develop/http-api/authentication/#jwt-user-tokens). + +### Installation + +First, install the MLflow client: + +```bash +pip install mlflow +``` + +### Programmatic Access + +There are two approaches for programmatic access to your ArangoDB MLflow service: + +#### Approach 1: Configure in Python Code + +```python +import mlflow +import os + +# Set authentication and tracking URI +os.environ['MLFLOW_TRACKING_TOKEN'] = 'your-bearer-token-here' +mlflow.set_tracking_uri("https://:8529/mlflow/") + +# Start logging your experiments +with mlflow.start_run(): + mlflow.log_artifact("local_file.txt") +``` + +#### Approach 2: Use Environment Variables + +Set the environment variables in your shell: + +```bash +export MLFLOW_TRACKING_URI="https://:8529/mlflow/" +export MLFLOW_TRACKING_TOKEN="your-bearer-token-here" +``` + +Then use MLflow normally in your Python code: + +```python +import mlflow + +# MLflow automatically uses the environment variables +with mlflow.start_run(): + mlflow.log_artifact("local_file.txt") +``` + +### Health Check + +To test whether the service is running, you can use the following snippet: + +```bash +curl -H "Authorization: Bearer your-bearer-token-here" https://:8529/mlflow/health +``` + +Expected output on success: HTTP `200` status with response body `OK` + +## API Reference + +For detailed API documentation, refer to the official MLflow REST API documentation: +[MLflow REST API Reference](https://mlflow.org/docs/latest/api_reference/rest-api.html) + +## Additional Resources + +The official MLflow documentation can be found at: +[MLflow Documentation](https://mlflow.org/docs/latest/index.html) \ No newline at end of file From 7dc6c94daee8cab52138f7671c025716242f7d4d Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Thu, 26 Jun 2025 09:39:39 +0200 Subject: [PATCH 10/16] Re-arrange content --- site/content/3.13/components/platform.md | 2 +- site/content/3.13/data-science/_index.md | 36 ++++--- .../{hybrid-rag.md => graphrag/_index.md} | 48 ++-------- .../data-science/graphrag/services/_index.md | 23 +++++ .../data-science/graphrag/services/gen-ai.md | 17 ++-- .../data-science/graphrag/services/mlflow.md | 12 ++- .../services/natural-language-to-aql.md | 95 +++++++++++-------- .../graphrag/services/rag-loader.md | 21 +++- .../graphrag/services/rag-retriever.md | 15 ++- .../{adapters => integrations}/_index.md | 6 +- .../arangodb-cugraph-adapter.md | 5 +- .../arangodb-dgl-adapter.md | 2 + .../arangodb-networkx-adapter.md | 5 +- .../arangodb-pyg-adapter.md | 2 + .../arangodb-rdf-adapter.md | 2 + .../data-science/integrations/langchain.md | 29 ++++++ 16 files changed, 200 insertions(+), 120 deletions(-) rename site/content/3.13/data-science/{hybrid-rag.md => graphrag/_index.md} (58%) create mode 100644 site/content/3.13/data-science/graphrag/services/_index.md rename genai_docs/GenAI/USER_FACING_DOCUMENTATION.md => site/content/3.13/data-science/graphrag/services/gen-ai.md (93%) rename genai_docs/arangodb-mlflow/USER_FACING_DOCUMENTATION.md => site/content/3.13/data-science/graphrag/services/mlflow.md (95%) rename genai_docs/natural_language_service/USER_GUIDE.md => site/content/3.13/data-science/graphrag/services/natural-language-to-aql.md (82%) rename genai_docs/RagLoader/USER_GUIDE.md => site/content/3.13/data-science/graphrag/services/rag-loader.md (94%) rename genai_docs/RagRetriever/USER_GUIDE.md => site/content/3.13/data-science/graphrag/services/rag-retriever.md (95%) rename site/content/3.13/data-science/{adapters => integrations}/_index.md (88%) rename site/content/3.13/data-science/{adapters => integrations}/arangodb-cugraph-adapter.md (99%) rename site/content/3.13/data-science/{adapters => integrations}/arangodb-dgl-adapter.md (99%) rename site/content/3.13/data-science/{adapters => integrations}/arangodb-networkx-adapter.md (99%) rename site/content/3.13/data-science/{adapters => integrations}/arangodb-pyg-adapter.md (99%) rename site/content/3.13/data-science/{adapters => integrations}/arangodb-rdf-adapter.md (99%) create mode 100644 site/content/3.13/data-science/integrations/langchain.md diff --git a/site/content/3.13/components/platform.md b/site/content/3.13/components/platform.md index 6b19dec493..121a67efe1 100644 --- a/site/content/3.13/components/platform.md +++ b/site/content/3.13/components/platform.md @@ -41,7 +41,7 @@ to access all of the platform features. 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. + 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 diff --git a/site/content/3.13/data-science/_index.md b/site/content/3.13/data-science/_index.md index b3158d8fc6..c6bcbee608 100644 --- a/site/content/3.13/data-science/_index.md +++ b/site/content/3.13/data-science/_index.md @@ -1,6 +1,6 @@ --- -title: Data Science -menuTitle: Data Science +title: Generative Artificial Intelligence (GenAI) and Data Science +menuTitle: GenAI & Data Science weight: 115 description: >- ArangoDB's set of tools and technologies enables analytics, machine learning, @@ -13,7 +13,7 @@ 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 +ArangoDB also offers a dedicated GenAI 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. @@ -25,17 +25,15 @@ engineering space can make use of ArangoDB's set of tools and technologies that enable analytics and machine learning on graph data. --> -## Data Science Suite +## GenAI Suite -The Data Science Suite (DSS) is comprised of three major components: +The GenAI Suite is comprised of two major components: -- [**HybridRAG**](#hybridrag): A complete solution for extracting entities +- [**GraphRAG**](#graphrag): 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. @@ -52,7 +50,17 @@ Alongside these components, you also get the following additional features: 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. + GenAI Suite services and build your own integrations. + +## Other tools and features + + + +The ArangoDB Platform includes the following features independent of the +GenAI Suite: + +- [**Graph Analytics**](#graph-analytics): Run graph algorithms such as PageRank + on dedicated compute resources. ## From graph to AI @@ -120,19 +128,19 @@ GraphML can answer questions like: For ArangoDB's enterprise-ready, graph-powered machine learning offering, see [ArangoGraphML](graphml/_index.md). -### HybridRAG +### GraphRAG -HybridRAG is ArangoDB's turn-key solution to turn your organization's data into +GraphRAG 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. -HybridRAG combines vector search for retrieving related text snippets -with graph-based retrieval augmented generation (GraphRAG) for context expansion +GraphRAG combines vector search for retrieving related text snippets +with graph-based retrieval augmented generation 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. -To learn more, see the [HybridRAG](hybrid-rag.md) documentation. +To learn more, see the [GraphRAG](graphrag/_index.md) documentation. ## Sample datasets diff --git a/site/content/3.13/data-science/hybrid-rag.md b/site/content/3.13/data-science/graphrag/_index.md similarity index 58% rename from site/content/3.13/data-science/hybrid-rag.md rename to site/content/3.13/data-science/graphrag/_index.md index c11cdaa8eb..712cb9c0b2 100644 --- a/site/content/3.13/data-science/hybrid-rag.md +++ b/site/content/3.13/data-science/graphrag/_index.md @@ -1,10 +1,10 @@ --- -title: Graph-powered HybridRAG -menuTitle: HybridRAG +title: GraphRAG +menuTitle: GraphRAG weight: 10 description: >- - ArangoDB's HybridRAG combines graph-based retrieval augmented generation - (GraphRAG) with Large Language Models (LLMs) for turbocharged Gen AI solutions + ArangoDB's GraphRAG solution combines graph-based retrieval augmented generation + with Large Language Models (LLMs) for turbocharged Gen AI solutions aliases: llm-knowledge-graphs # TODO: Repurpose for GenAI @@ -29,13 +29,13 @@ 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. -The HybridRAG component of the Data Science Suite brings all the capabilities +The GraphRAG component of the GenAI Suite brings all the capabilities together with an easy-to-use interface so you can make the knowledge accessible to your organization. -## HybridRAG +## ArangoDB GraphRAG -ArangoDB's HybridRAG solution democratizes the creation and usage of knowledge +ArangoDB's GraphRAG solution democratizes the creation and usage of knowledge graphs with a unique combination of vector search, graphs, and LLMs in a single product. @@ -60,16 +60,10 @@ the following tasks: - End-to-end knowledge graph construction - (Text) Embeddings -![ArangoDB Knowledge Graphs and LLMs](../../images/ArangoDB-knowledge-graphs-meets-llms.png) +![ArangoDB Knowledge Graphs and LLMs](../../../images/ArangoDB-knowledge-graphs-meets-llms.png) ### Examples -### Services - -#### Service A - -#### Service B - ### Interfaces {{< tabs "interfaces" >}} @@ -79,31 +73,9 @@ the following tasks: {{< /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. - -LangChain enables applications that are: -- Data-aware (connect a language model to other sources of data) -- Agentic (allow a language model to interact with its environment) - -The ArangoDB integration with LangChain provides you the ability to analyze -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 - -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 -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). diff --git a/site/content/3.13/data-science/graphrag/services/_index.md b/site/content/3.13/data-science/graphrag/services/_index.md new file mode 100644 index 0000000000..8f7a628772 --- /dev/null +++ b/site/content/3.13/data-science/graphrag/services/_index.md @@ -0,0 +1,23 @@ +--- +title: GraphRAG services +menuTitle: Services +descriptions: >- + The GraphRAG solution is implemented as a set of Kubernetes services +weight: 10 +--- +## Services + +### GenAI + +### RAGLoader + +### RAGRetriever + +### LLM fine tuning + +### Auto-Tuna + +### Triton integration + +### Natural language service + diff --git a/genai_docs/GenAI/USER_FACING_DOCUMENTATION.md b/site/content/3.13/data-science/graphrag/services/gen-ai.md similarity index 93% rename from genai_docs/GenAI/USER_FACING_DOCUMENTATION.md rename to site/content/3.13/data-science/graphrag/services/gen-ai.md index 433e4bd932..8f13367645 100644 --- a/genai_docs/GenAI/USER_FACING_DOCUMENTATION.md +++ b/site/content/3.13/data-science/graphrag/services/gen-ai.md @@ -1,10 +1,15 @@ -# GenAI-Service - +--- +title: GenAI Orchestration Service +menuTitle: GenAI +description: >- + The GenAI orchestrator service installs, manages, and runs AI-based services + in your Kubernetes cluster +# TODO: Shouldn't this refer to the ArangoDB Platform instead? +weight: 5 +--- ## Description -The GenAI orchestrator service is a service that is able to install, manage, and run AI-based services in your Kubernetes cluster. - -The basic operations are: +The basic operations that the GenAI orchestration service carries out are the following: - Install a service - Uninstall a service - Get the status of a service @@ -177,4 +182,4 @@ Expected output on success: `{"status":"OK"}` ## API Reference -For detailed API documentation, visit: [GenAI-Service API Reference](https://arangoml.github.io/platform-dss-api/GenAI-Service/proto/index.html) \ No newline at end of file +For detailed API documentation, visit: [GenAI-Service API Reference](https://arangoml.github.io/platform-dss-api/GenAI-Service/proto/index.html) diff --git a/genai_docs/arangodb-mlflow/USER_FACING_DOCUMENTATION.md b/site/content/3.13/data-science/graphrag/services/mlflow.md similarity index 95% rename from genai_docs/arangodb-mlflow/USER_FACING_DOCUMENTATION.md rename to site/content/3.13/data-science/graphrag/services/mlflow.md index b25ec4a74e..3b0dabb30e 100644 --- a/genai_docs/arangodb-mlflow/USER_FACING_DOCUMENTATION.md +++ b/site/content/3.13/data-science/graphrag/services/mlflow.md @@ -1,5 +1,11 @@ -# ArangoDB-MLflow-Service - +--- +title: ArangoDB MLflow Service +menuTitle: MLflow +description: >- + The ArangoDB MLflow Service integrates the MLflow platform for managing the + full machine learning lifecycle into the ArangoDB Platform +weight: 25 +--- ## Overview The ArangoDB MLflow service is a service that hosts the official MLflow application in your Kubernetes cluster and connects it automatically to the ArangoDB environment, e.g. for registering the LLM to be self-hosted and used by services requiring LLMs (natural-language-service, RAGLoader, RAGRetriever). @@ -119,4 +125,4 @@ For detailed API documentation, refer to the official MLflow REST API documentat ## Additional Resources The official MLflow documentation can be found at: -[MLflow Documentation](https://mlflow.org/docs/latest/index.html) \ No newline at end of file +[MLflow Documentation](https://mlflow.org/docs/latest/index.html) diff --git a/genai_docs/natural_language_service/USER_GUIDE.md b/site/content/3.13/data-science/graphrag/services/natural-language-to-aql.md similarity index 82% rename from genai_docs/natural_language_service/USER_GUIDE.md rename to site/content/3.13/data-science/graphrag/services/natural-language-to-aql.md index bf92cf1f3a..1aab97abc1 100644 --- a/genai_docs/natural_language_service/USER_GUIDE.md +++ b/site/content/3.13/data-science/graphrag/services/natural-language-to-aql.md @@ -1,9 +1,18 @@ -# Natural Language to AQL Translation Service (txt2aql) - +--- +title: Natural Language to AQL Translation Service (txt2aql) +menuTitle: txt2aql +description: >- + The Natural Language to AQL Translation Service is a powerful tool that allows + you to interact with your ArangoDB database using natural language queries +weight: 20 +--- ## 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. + +This service 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 @@ -13,12 +22,14 @@ The Natural Language to AQL Translation Service is a powerful tool that allows y ## 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 @@ -42,9 +53,11 @@ 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 @@ -63,64 +76,62 @@ These parameters must be provided in the install request sent to GenAI service. - `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?" -} -``` + ```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"] - } -} -``` - + ```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 -``` + ```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 -``` + ```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 -``` + ```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 -``` + ```bash + grpcurl -plaintext localhost:9090 txt2aql.Txt2AqlService/HealthCheck + ``` ## Output Formats diff --git a/genai_docs/RagLoader/USER_GUIDE.md b/site/content/3.13/data-science/graphrag/services/rag-loader.md similarity index 94% rename from genai_docs/RagLoader/USER_GUIDE.md rename to site/content/3.13/data-science/graphrag/services/rag-loader.md index 73b6506ebb..eb94d7a457 100644 --- a/genai_docs/RagLoader/USER_GUIDE.md +++ b/site/content/3.13/data-science/graphrag/services/rag-loader.md @@ -1,11 +1,22 @@ -# RagLoader User Guide - +--- +title: RagLoader Service +menuTitle: RagLoader +description: >- + The RagLoader service helps you transform your text document into knowledge graph, + making it easier to analyze and understand complex information +weight: 10 +--- ## 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. +The RagLoader service lets you turn text files into a knowledge graph. +It supports the following text formats with UTF-8 encoding: +- Plain text +- Markdown +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: diff --git a/genai_docs/RagRetriever/USER_GUIDE.md b/site/content/3.13/data-science/graphrag/services/rag-retriever.md similarity index 95% rename from genai_docs/RagRetriever/USER_GUIDE.md rename to site/content/3.13/data-science/graphrag/services/rag-retriever.md index 5a11fb8b9c..2b1064df77 100644 --- a/genai_docs/RagRetriever/USER_GUIDE.md +++ b/site/content/3.13/data-science/graphrag/services/rag-retriever.md @@ -1,8 +1,15 @@ -# RagRetriever User Guide - +--- +title: RagRetriever Service +menuTitle: RagRetriever +description: >- + RagRetriever is a powerful service that enables intelligent search and + retrieval from knowledge graphs created by the GraphRAG Importer +# TODO: GraphRAG Importer == RagLoader? +weight: 15 +--- ## 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: +The RagRetriever service 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. @@ -16,6 +23,8 @@ Key features: - 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. diff --git a/site/content/3.13/data-science/adapters/_index.md b/site/content/3.13/data-science/integrations/_index.md similarity index 88% rename from site/content/3.13/data-science/adapters/_index.md rename to site/content/3.13/data-science/integrations/_index.md index 75d8c4558b..3b1a028811 100644 --- a/site/content/3.13/data-science/adapters/_index.md +++ b/site/content/3.13/data-science/integrations/_index.md @@ -1,10 +1,12 @@ --- -title: Adapters -menuTitle: Adapters +title: ArangoDB integrations for data science +menuTitle: Integrations weight: 50 description: >- ArangoDB offers multiple adapters that enable seamless integration with data science tools +aliases: + - adapters --- ArangoDB Adapters provide a convenient way to integrate ArangoDB with popular data science tools. By enabling you to to use your preferred programming diff --git a/site/content/3.13/data-science/adapters/arangodb-cugraph-adapter.md b/site/content/3.13/data-science/integrations/arangodb-cugraph-adapter.md similarity index 99% rename from site/content/3.13/data-science/adapters/arangodb-cugraph-adapter.md rename to site/content/3.13/data-science/integrations/arangodb-cugraph-adapter.md index fffdffc4a6..8d73c6fe06 100644 --- a/site/content/3.13/data-science/adapters/arangodb-cugraph-adapter.md +++ b/site/content/3.13/data-science/integrations/arangodb-cugraph-adapter.md @@ -4,16 +4,15 @@ menuTitle: cuGraph weight: 10 description: >- The cuGraph Adapter exports graphs from ArangoDB into RAPIDS cuGraph, a library of collective GPU-accelerated graph algorithms, and vice-versa +aliases: + - ../adapters/arangodb-cugraph-adapter --- - - {{< tip >}} ArangoDB now has a closer integration with NetworkX allowing NetworkX users to persist their graphs in ArangoDB & leverage GPU-accelerated graph analytics via cuGraph. [Learn more here](https://arangodb.com/introducing-the-arangodb-networkx-persistence-layer/). {{< /tip >}} - While offering a similar API and set of graph algorithms to NetworkX, [RAPIDS cuGraph](https://docs.rapids.ai/api/cugraph/stable/) library is GPU-based. Especially for large graphs, this diff --git a/site/content/3.13/data-science/adapters/arangodb-dgl-adapter.md b/site/content/3.13/data-science/integrations/arangodb-dgl-adapter.md similarity index 99% rename from site/content/3.13/data-science/adapters/arangodb-dgl-adapter.md rename to site/content/3.13/data-science/integrations/arangodb-dgl-adapter.md index 4d654bfd6c..efb246db4f 100644 --- a/site/content/3.13/data-science/adapters/arangodb-dgl-adapter.md +++ b/site/content/3.13/data-science/integrations/arangodb-dgl-adapter.md @@ -4,6 +4,8 @@ menuTitle: DGL weight: 20 description: >- The DGL Adapter exports graphs from ArangoDB into Deep Graph Library (DGL), a Python package for graph neural networks, and vice-versa +aliases: + - ../adapters/arangodb-dgl-adapter --- The [Deep Graph Library (DGL)](https://www.dgl.ai/) is an easy-to-use, high performance and scalable diff --git a/site/content/3.13/data-science/adapters/arangodb-networkx-adapter.md b/site/content/3.13/data-science/integrations/arangodb-networkx-adapter.md similarity index 99% rename from site/content/3.13/data-science/adapters/arangodb-networkx-adapter.md rename to site/content/3.13/data-science/integrations/arangodb-networkx-adapter.md index 58963947b0..fac703e0f0 100644 --- a/site/content/3.13/data-science/adapters/arangodb-networkx-adapter.md +++ b/site/content/3.13/data-science/integrations/arangodb-networkx-adapter.md @@ -4,16 +4,15 @@ menuTitle: NetworkX weight: 5 description: >- The NetworkX Adapter allows you to export graphs from ArangoDB into NetworkX for graph analysis with Python and vice-versa +aliases: + - ../adapters/arangodb-networkx-adapter --- - - {{< tip >}} ArangoDB now has a closer integration with NetworkX allowing NetworkX users to persist their graphs in ArangoDB & leverage GPU-accelerated graph analytics via cuGraph. [Learn more here](https://arangodb.com/introducing-the-arangodb-networkx-persistence-layer/). {{< /tip >}} - [NetworkX](https://networkx.org/) is a commonly used tool for analysis of network-data. If your analytics use cases require the use of all your graph data, for example, diff --git a/site/content/3.13/data-science/adapters/arangodb-pyg-adapter.md b/site/content/3.13/data-science/integrations/arangodb-pyg-adapter.md similarity index 99% rename from site/content/3.13/data-science/adapters/arangodb-pyg-adapter.md rename to site/content/3.13/data-science/integrations/arangodb-pyg-adapter.md index 361e602a7c..f24a681c3d 100644 --- a/site/content/3.13/data-science/adapters/arangodb-pyg-adapter.md +++ b/site/content/3.13/data-science/integrations/arangodb-pyg-adapter.md @@ -4,6 +4,8 @@ menuTitle: PyG weight: 15 description: >- The PyG Adapter exports Graphs from ArangoDB into PyTorch Geometric (PyG), a PyTorch-based Graph Neural Network library, and vice-versa +aliases: + - ../adapters/arangodb-pyg-adapter --- PyTorch Geometric (PyG) is a library built upon [PyTorch](https://pytorch.org/) to easily write and train Graph Neural Networks (GNNs) for a wide range of diff --git a/site/content/3.13/data-science/adapters/arangodb-rdf-adapter.md b/site/content/3.13/data-science/integrations/arangodb-rdf-adapter.md similarity index 99% rename from site/content/3.13/data-science/adapters/arangodb-rdf-adapter.md rename to site/content/3.13/data-science/integrations/arangodb-rdf-adapter.md index 87c171a7de..e0c2f71e77 100644 --- a/site/content/3.13/data-science/adapters/arangodb-rdf-adapter.md +++ b/site/content/3.13/data-science/integrations/arangodb-rdf-adapter.md @@ -4,6 +4,8 @@ menuTitle: RDF weight: 25 description: >- ArangoRDF allows you to export graphs from ArangoDB into RDF and vice-versa +aliases: + - ../adapters/arangodb-rdf-adapter --- RDF is a standard model for data interchange on the Web. RDF has features that facilitate data merging even if the underlying schemas differ, and it diff --git a/site/content/3.13/data-science/integrations/langchain.md b/site/content/3.13/data-science/integrations/langchain.md new file mode 100644 index 0000000000..48da4bd49b --- /dev/null +++ b/site/content/3.13/data-science/integrations/langchain.md @@ -0,0 +1,29 @@ +--- +title: ArangoDB integration with LangChain +menuTitle: LangChain +weight: 30 +description: >- + A LangChain integration for using LLMs to provide a natural language interface + for the data stored in ArangoDB +--- +[LangChain](https://www.langchain.com/) is a framework for developing applications +powered by language models. + +LangChain enables applications that are: +- Data-aware (connect a language model to other sources of data) +- Agentic (allow a language model to interact with its environment) + +The ArangoDB integration with LangChain provides you the ability to analyze +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 + +The [ArangoDB QA chain notebook](https://langchain-langchain.vercel.app/docs/integrations/graphs/arangodb/) +shows how to use LLMs to provide a natural language interface to an ArangoDB +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). From d11e700a85f8ddf5952ac58c6982efb12944beaf Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Thu, 26 Jun 2025 10:50:08 +0200 Subject: [PATCH 11/16] Fix links --- site/content/3.13/aql/functions/vector.md | 2 +- .../indexing/working-with-indexes/vector-indexes.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/3.13/aql/functions/vector.md b/site/content/3.13/aql/functions/vector.md index e6a6de0134..45341b8ea8 100644 --- a/site/content/3.13/aql/functions/vector.md +++ b/site/content/3.13/aql/functions/vector.md @@ -12,7 +12,7 @@ To use vector search, you need to have vector embeddings stored in documents and the attribute that stores them needs to be indexed by a [vector index](../../index-and-search/indexing/working-with-indexes/vector-indexes.md). -You can calculate vector embeddings using [ArangoDB's GraphML](../../data-science/arangographml/_index.md) +You can calculate vector embeddings using [ArangoDB's GraphML](../../data-science/graphml/_index.md) capabilities (available in ArangoGraph) or using external tools. {{< warning >}} diff --git a/site/content/3.13/index-and-search/indexing/working-with-indexes/vector-indexes.md b/site/content/3.13/index-and-search/indexing/working-with-indexes/vector-indexes.md index 90b82edbf9..236093878b 100644 --- a/site/content/3.13/index-and-search/indexing/working-with-indexes/vector-indexes.md +++ b/site/content/3.13/index-and-search/indexing/working-with-indexes/vector-indexes.md @@ -33,7 +33,7 @@ startup option needs to be enabled on the deployment you want to restore to. {{< /warning >}} 1. Enable the experimental vector index feature. -2. Calculate vector embeddings using [ArangoDB's GraphML](../../../data-science/arangographml/_index.md) +2. Calculate vector embeddings using [ArangoDB's GraphML](../../../data-science/graphml/_index.md) capabilities (available in ArangoGraph) or using external tools. Store each vector as an attribute in the respective document. 3. Create a vector index over this attribute. You need to choose which From e82b2f83ffc12bd7d88edc315216aac56703f04a Mon Sep 17 00:00:00 2001 From: Paula Date: Thu, 3 Jul 2025 13:26:30 +0200 Subject: [PATCH 12/16] fix conflicts --- .../3.13/data-science/graphml/_index.md | 2 +- .../3.13/data-science/graphml/deploy.md | 78 -- .../data-science/graphml/getting-started.md | 968 ------------------ 3 files changed, 1 insertion(+), 1047 deletions(-) delete mode 100644 site/content/3.13/data-science/graphml/deploy.md delete mode 100644 site/content/3.13/data-science/graphml/getting-started.md diff --git a/site/content/3.13/data-science/graphml/_index.md b/site/content/3.13/data-science/graphml/_index.md index ba8e2d6c46..00c79ec1a0 100644 --- a/site/content/3.13/data-science/graphml/_index.md +++ b/site/content/3.13/data-science/graphml/_index.md @@ -1,7 +1,7 @@ --- title: ArangoDB GraphML menuTitle: GraphML -weight: 125 +weight: 15 description: >- Boost your machine learning models with graph data using ArangoDB's advanced GraphML capabilities aliases: diff --git a/site/content/3.13/data-science/graphml/deploy.md b/site/content/3.13/data-science/graphml/deploy.md deleted file mode 100644 index 78676dd08c..0000000000 --- a/site/content/3.13/data-science/graphml/deploy.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Deploy ArangoGraphML -menuTitle: Deploy -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 - -ArangoDB offers two deployment options, tailored to suit diverse requirements -and infrastructure preferences: -- Managed cloud service via the [ArangoGraph Insights Platform](https://dashboard.arangodb.cloud/home?utm_source=docs&utm_medium=cluster_pages&utm_campaign=docs_traffic) -- Self-managed solution via the [ArangoDB Kubernetes Operator](https://github.com/arangodb/kube-arangodb) - -### ArangoGraphML - -ArangoGraphML provides enterprise-ready Graph Machine Learning as a -Cloud Service via Jupyter Notebooks that run on the -[ArangoGraph Insights Platform](https://dashboard.arangodb.cloud/home?utm_source=docs&utm_medium=cluster_pages&utm_campaign=docs_traffic). - -{{< tip >}} -To get access to ArangoGraphML services and packages, -[get in touch](https://www.arangodb.com/contact/) -with the ArangoDB team. -{{< /tip >}} - -- **Accessible at all levels** - - Low code UI - - Notebooks - - APIs -- **Full usability** - - MLOps lifecycle - - Metrics - - Metadata capture - - Model management - -![ArangoGraphML Pipeline](../../../images/ArangoGraphML_Pipeline.png) - -#### Setup - -The ArangoGraphML managed-service runs on the -[ArangoGraph Insights Platform](https://dashboard.arangodb.cloud/home?utm_source=docs&utm_medium=cluster_pages&utm_campaign=docs_traffic). -It offers a pre-configured environment where everything, -including necessary components and configurations, comes preloaded. You don't -need to set up or configure the infrastructure, and can immediately start using the -GraphML functionalities. - -To summarize, all you need to do is: -1. Sign up for an [ArangoGraph account](https://dashboard.arangodb.cloud/home?utm_source=docs&utm_medium=cluster_pages&utm_campaign=docs_traffic). -2. Create a new [deployment in ArangoGraph](../../arangograph/deployments/_index.md#how-to-create-a-new-deployment). -3. Start using the ArangoGraphML functionalities. - -### Self-managed ArangoGraphML - -The self-managed solution enables you to deploy and manage ArangoML within your -Kubernetes cluster using the [ArangoDB Kubernetes Operator](https://github.com/arangodb/kube-arangodb). - -The self-managed package includes the same features as in ArangoGraphML. -The primary distinction lies in the environment setup: with the self-managed -solution, you have direct control over configuring your environment. - -#### Setup - -You can run ArangoGraphML in your Kubernetes -cluster provided you already have a running `ArangoDeployment`. If you don't -have one yet, consider checking the installation guide of the -[ArangoDB Kubernetes Operator](https://arangodb.github.io/kube-arangodb/docs/using-the-operator.html) -and the [ArangoDeployment Custom Resource](https://arangodb.github.io/kube-arangodb/docs/deployment-resource-reference.html) -description. - -To start ArangoGraphML in your Kubernetes cluster, follow the instructions provided -in the [ArangoMLExtension Custom Resource](https://arangodb.github.io/kube-arangodb/docs/mlextension-resource.html) -description. Once the `CustomResource` has been created and the ArangoGraphML extension -is ready, you can start using it. \ No newline at end of file diff --git a/site/content/3.13/data-science/graphml/getting-started.md b/site/content/3.13/data-science/graphml/getting-started.md deleted file mode 100644 index 51b756d81d..0000000000 --- a/site/content/3.13/data-science/graphml/getting-started.md +++ /dev/null @@ -1,968 +0,0 @@ ---- -title: Getting Started with ArangoGraphML -menuTitle: Getting Started -weight: 10 -description: >- - How to control all resources inside ArangoGraphML in a scriptable manner -aliases: - - ../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. - -The `arangoml` is a Python Package allowing you to manage all of the necessary ArangoGraphML components, including: -- **Project Management**: Projects are a metadata-tracking entity that sit at the top level of ArangoGraphML. All activities must link to a project. -- **Featurization**: The step of converting human-understandable data to machine-understandable data (i.e features), such that it can be used to train Graph Neural Networks (GNNs). -- **Training**: Train a set of models based on the name of the generated/existing features, and a definition of the ML Task we want to solve (e.g Node Classification, Embedding Generation). -- **Model Selection**: Select the best model based on the metrics generated during training. -- **Predictions**: Generate predictions based on the selected model, and persit the results to the source graph (either in the source document, or in a new collection). - -{{< tip >}} -To enable the ArangoGraphML services in the ArangoGraph platform, -[get in touch](https://www.arangodb.com/contact/) -with the ArangoDB team. Regular notebooks in ArangoGraph don't include the -`arangoml` package. -{{< /tip >}} - -ArangoGraphML's suite of services and packages is driven by **"specifications"**. These specifications are standard Python dictionaries that describe the task being performed, & the data being used. The ArangoGraphML services work closely together, with the previous task being used as the input for the next. - -Let's take a look at using the `arangoml` package to: - -1. Manage projects -2. Featurize data -3. Submit Training Jobs -4. Evaluate Model Metrics -5. Generate Predictions - -## Initialize ArangoML - -{{< tabs "arangoml" >}} - -{{< tab "ArangoGraphML" >}} - -**API Documentation: [arangoml.ArangoMLMagics.enable_arangoml](https://arangoml.github.io/arangoml/magics.html#arangoml.magic.ArangoMLMagics.enable_arangoml)** - -The `arangoml` package comes pre-loaded with every ArangoGraphML notebook environment. -To start using it, simply import it, and enable it via a Jupyter Magic Command. - -```py -arangoml = %enable_arangoml -``` - -{{< tip >}} -ArangoGraphML comes with other ArangoDB Magic Commands! See the full list [here](https://arangoml.github.io/arangoml/magics.html). -{{< /tip >}} - -{{< /tab >}} - -{{< tab "Self-managed" >}} - -**API Documentation: [arangoml.ArangoML](https://arangoml.github.io/arangoml/client.html#arangoml.main.ArangoML)** - -The `ArangoML` class is the main entry point for the `arangoml` package. -It has the following parameters: -- `client`: An instance of arango.client.ArangoClient. Defaults to `None`. If not provided, the **hosts** argument must be provided. -- `hosts`: The ArangoDB host(s) to connect to. This can be a single host, or a - list of hosts. -- `username`: The ArangoDB username to use for authentication. -- `password`: The ArangoDB password to use for authentication. -- `user_token`: The ArangoDB user token to use for authentication. - This is an alternative to username/password authentication. -- `ca_cert_file`: The path to the CA certificate file to use for TLS - verification. Defaults to `None`. -- `api_endpoint`: The URL to the ArangoGraphML API Service. -- `settings_files`: A list of secrets files to be loaded as settings. Parameters provided as arguments will override those in the settings files (e.g `settings.toml`). -- `version`: The ArangoML API date version. Defaults to the latest version. - -It is possible to instantiate an ArangoML object in multiple ways: - -1. Via parameters -```py -from arangoml import ArangoML - -arangoml = ArangoML( - hosts="http://localhost:8529" - username="root", - password="password", - # ca_cert_file="/path/to/ca.pem", - # user_token="..." - api_endpoint="http://localhost:8501", -) -``` - -2. Via parameters and a custom `ArangoClient` instance -```py -from arangoml import ArangoML -from arango import ArangoClient - -client = ArangoClient( - hosts="http://localhost:8529", - verify_override="/path/to/ca.pem", - hosts_resolver=..., - ... -) - -arangoml = ArangoML( - client=client, - username="root", - password="password", - # user_token="..." - api_endpoint="http://localhost:8501", -) -``` - -3. Via environment variables -```py -import os -from arangoml import ArangoML - -os.environ["ARANGODB_HOSTS"] = "http://localhost:8529" -os.environ["ARANGODB_CA_CERT_FILE"]="/path/to/ca.pem" -os.environ["ARANGODB_USER"] = "root" -os.environ["ARANGODB_PW"] = "password" -# os.environ["ARANGODB_USER_TOKEN"] = "..." -os.environ["ML_API_SERVICES_ENDPOINT"] = "http://localhost:8501" - -arangoml = ArangoML() -``` - -4. Via configuration files -```py -import os -from arangoml import ArangoML - -arangoml = ArangoML(settings_files=["settings_1.toml", "settings_2.toml"]) -``` - -5. Via a Jupyter Magic Command - -**API Documentation: [arangoml.ArangoMLMagics.enable_arangoml](https://arangoml.github.io/arangoml/magics.html#arangoml.magic.ArangoMLMagics.enable_arangoml)** - -``` -%load_ext arangoml -%enable_arangoml -``` -{{< info >}} -This assumes you are working out of a Jupyter Notebook environment, and -have set the environment variables in the notebook environment with user -authentication that has **_system** access. -{{< /info >}} - -{{< tip >}} -Running `%load_ext arangoml` also provides access to other [ArangoGraphML -Jupyter Magic Commands](https://arangoml.github.io/arangoml/magics.html). -{{< /tip >}} - -{{< /tab >}} - -{{< /tabs >}} - -## Load the database - -This example is using ArangoML to predict the **class** of `Events` in a -Knowledge Graph constructed from the [GDELT Project](https://www.gdeltproject.org/). - -> GDELT monitors the world's news media from nearly every corner of every - country in print, broadcast, and web formats, in over 100 languages, every - moment of every day. [...] Put simply, the GDELT Project is a realtime open - data global graph over human society as seen through the eyes of the world's - news media, reaching deeply into local events, reaction, discourse, and - emotions of the most remote corners of the world in near-realtime and making - all of this available as an open data firehose to enable research over human - society. - -The events used range from peaceful protests to significant battles in Angola. -The image below depicts the connections around an example event: - -![Example Event](../../../images/ArangoML_open_intelligence_sample.png) - -You can also see a larger portion of this graph, showing how the events, actors, -news sources, and locations are interconnected into a large graph. - -![Example Event](../../../images/ArangoML_open_intelligence_visualization.png) - -Let's get started! - -{{< tabs "arangoml" >}} - -{{< tab "ArangoGraphML" >}} - -The [`arango-datasets`](../../components/tools/arango-datasets.md) Python package -allows you to load pre-defined datasets into ArangoDB. It comes pre-installed in the -ArangoGraphML notebook environment. - -```py -DATASET_NAME = "OPEN_INTELLIGENCE_ANGOLA" - -%delete_database {DATASET_NAME} -%create_database {DATASET_NAME} -%use_database {DATASET_NAME} -%load_dataset {DATASET_NAME} -``` - -{{< /tab >}} - -{{< tab "Self-managed" >}} - -The [`arango-datasets`](../../components/tools/arango-datasets.md) Python package -allows you to load pre-defined datasets into ArangoDB. It can be installed with the -following command: - -``` -pip install arango-datasets -``` - -```py -from arango_datasets.datasets import Datasets - -DATASET_NAME = "OPEN_INTELLIGENCE_ANGOLA" - -db = arangoml.client.db( - name=DATASET_NAME, - username=arangoml.settings.get("ARANGODB_USER"), - password=arangoml.settings.get("ARANGODB_PW"), - user_token=arangoml.settings.get("ARANGODB_USER_TOKEN"), - verify=True -) - -Datasets(dataset_db).load(DATASET_NAME) -``` -{{< /tab >}} - -{{< /tabs >}} - -## Projects - -**API Documentation: [ArangoML.projects](https://arangoml.github.io/arangoml/api.html#projects)** - -Projects are an important reference used throughout the entire ArangoGraphML -lifecycle. All activities link back to a project. The creation of the project -is very simple. - -### Get/Create a project -```py -project = arangoml.get_or_create_project(DATASET_NAME) -``` - -### List projects - -```py -arangoml.projects.list_projects() -``` - -## Featurization - -**API Documentation: [ArangoML.jobs.featurize](https://arangoml.github.io/arangoml/api.html#agml_api.jobs.v1.api.jobs_api.JobsApi.featurize)** - -**The Featurization Service depends on a `Featurization Specification` that contains**: -- `featurizationName`: A name for the featurization task. - -- `projectName`: The associated project name. You can use `project.name` here - if it was created or retrieved as described above. - -- `graphName`: The associated graph name that exists within the database. - -- `featureSetID` Optional: The ID of an existing Feature Set to re-use. If provided, the `metagraph` dictionary can be ommitted. Defaults to `None`. - -- `featurizationConfiguration` Optional: The optional default configuration to be applied - across all features. Individual collection feature settings override this option. - - - `featurePrefix`: The prefix to be applied to all individual features generated. Default is `feat_`. - - - `outputName`: Adjust the default feature name. This can be any valid ArangoDB attribute name. Defaults to `x`. - - - `dimensionalityReduction`: Object configuring dimensionality reduction. - - `disabled`: Whether to disable dimensionality reduction. Default is `false`, - therefore dimensionality reduction is applied after Featurization by default. - - `size`: The number of dimensions to reduce the feature length to. Default is `512`. - - - `defaultsPerFeatureType`: A dictionary mapping each feature to how missing or mismatched values should be handled. The keys of this dictionary are the features, and the values are sub-dictionaries with the following keys: - - `missing`: A sub-dictionary detailing how missing values should be handled. - - `strategy`: The strategy to use for missing values. Options include `REPLACE` or `RAISE`. - - `replacement`: The value to replace missing values with. Only needed if `strategy` is `REPLACE`. - - `mismatch`: A sub-dictionary detailing how mismatched values should be handled. - - `strategy`: The strategy to use for mismatched values. Options include `REPLACE`, `RAISE`, `COERCE_REPLACE`, or `COERCE_RAISE`. - - `replacement`: The value to replace mismatched values with. Only needed if `strategy` is `REPLACE`, or `COERCE_REPLACE`. - -- `jobConfiguration` Optional: A set of configurations that are applied to the job. - - `batchSize`: The number of documents to process in a single batch. Default is `32`. - - `runAnalysisChecks`: Whether to run analysis checks, used to perform a high-level analysis of the data quality before proceeding. Default is `true`. - - `skipLabels`: Skips the featurization process for attributes marked as `label`. Default is `false`. - - `useFeatureStore`: Enables the use of the Feature Store database, which allows you to store features separately from your Source Database. Default is `false`, therefore features are written to the source graph. - - `overwriteFSGraph`: Whether to overwrite the Feature Store Graph if features were previously generated. Default is `false`, therefore features are written to an existing Feature Store Graph.s - - `writeToSourceGraph`: Whether to store the generated features on the Source Graph. Default is `true`. - -- `metagraph`: Metadata to represent the vertex & edge collections of the graph. - - `vertexCollections`: A dictionary mapping the vertex collection names to the following values: - - `features`: A dictionary mapping document properties to the following values: - - `featureType`: The type of feature. Options include `text`, `category`, `numeric`, or `label`. - - `config`: Collection-level configuration settings. - - `featurePrefix`: Identical to global `featurePrefix` but for this collection. - - `dimensionalityReduction`: Identical to global `dimensionalityReduction` but for this collection. - - `outputName`: Identical to global `outputName`, but specifically for this collection. - - `defaultsPerFeatureType`: Identical to global `defaultsPerFeatureType`, but specifically for this collection. - - `edgeCollections`: A dictionary mapping the edge collection names to an empty dictionary, as edge attributes are not currently supported. - -The Featurization Specification example is used for the GDELT dataset: -- It featurizes the `name` attribute of the `Actor`, `Class`, `Country`, - `Source`, `Location`, and `Region` collections as a `text` features. -- It featurizes the `description` attribute of the `Event` collection as a - `text` feature. -- It featurizes the `label` attribute of the `Event` collection as a `label` - feature (this is the attribute you want to predict). -- It featurizes the `sourceScale` attribute of the `Source` collection as a - `category` feature. -- It featurizes the `name` attribute of the `Region` collection as a - `category` feature. - -```py -# 1. Define the Featurization Specification - -featurization_spec = { - "databaseName": dataset_db.name, - "projectName": project.name, - "graphName": graph.name, - "featurizationName": f"{DATASET_NAME}_Featurization", - "featurizationConfiguration": { - "featurePrefix": "feat_", - "dimensionalityReduction": { "size": 256 }, - "outputName": "x" - }, - "jobConfiguration": { - "batchSize": 512, - "useFeatureStore": False, - "runAnalysisChecks": False, - }, - "metagraph": { - "vertexCollections": { - "Actor": { - "features": { - "name": { - "featureType": "text", - }, - } - }, - "Country": { - "features": { - "name": { - "featureType": "text", - } - } - }, - "Event": { - "features": { - "description": { - "featureType": "text", - }, - "label": { - "featureType": "label", - }, - } - }, - "Source": { - "features": { - "name": { - "featureType": "text", - }, - "sourceScale": { - "featureType": "category", - }, - } - }, - "Location": { - "features": { - "name": { - "featureType": "text", - } - } - }, - "Region": { - "features": { - "name": { - "featureType": "category", - }, - } - } - }, - "edgeCollections": { - "eventActor": {}, - "hasSource": {}, - "hasLocation": {}, - "inCountry": {}, - "inRegion": {}, - } - } -} -``` - -Once the specification has been defined, a Featurization Job can be triggered using the `arangoml.jobs.featurize` method: - -```py -# 2. Submit a Featurization Job - -featurization_job = arangoml.jobs.featurize(featurization_spec) -``` - -Once a Featurization Job has been submitted, you can wait for it to complete using the `arangoml.wait_for_featurization` method: - -```py -# 3. Wait for the Featurization Job to complete - -featurization_job_result = arangoml.wait_for_featurization(featurization_job.job_id) -``` - - -**Example Output:** -```py -{ - "job_id": "16349541", - "output_db_name": "OPEN_INTELLIGENCE_ANGOLA", - "graph": "OPEN_INTELLIGENCE_ANGOLA", - "feature_set_id": "16349537", - "feature_set_ids": [ - "16349537" - ], - "vertexCollections": { - "Actor": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Class": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Country": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Event": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x", - "y": "OPEN_INTELLIGENCE_ANGOLA_y" - }, - "Source": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Location": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Region": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - } - }, - "edgeCollections": { - "eventActor": {}, - "hasSource": {}, - "hasLocation": {}, - "inCountry": {}, - "inRegion": {}, - "subClass": {}, - "type": {} - }, - "label_field": "OPEN_INTELLIGENCE_ANGOLA_y", - "input_field": "OPEN_INTELLIGENCE_ANGOLA_x", - "feature_set_id_to_results": { - "16349537": { - "feature_set_id": "16349537", - "output_db_name": "OPEN_INTELLIGENCE_ANGOLA", - "graph": "OPEN_INTELLIGENCE_ANGOLA", - "vertexCollections": { - "Actor": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Class": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Country": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Event": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x", - "y": "OPEN_INTELLIGENCE_ANGOLA_y" - }, - "Source": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Location": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Region": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - } - }, - "edgeCollections": { - "eventActor": {}, - "hasSource": {}, - "hasLocation": {}, - "inCountry": {}, - "inRegion": {}, - "subClass": {}, - "type": {} - }, - "label_field": "OPEN_INTELLIGENCE_ANGOLA_y", - "input_field": "OPEN_INTELLIGENCE_ANGOLA_x", - "is_feature_store": false, - "target_collection": "Event" - } - }, - "is_feature_store": false, - "target_collection": "Event" -} -``` - -You can also cancel a Featurization Job using the `arangoml.jobs.cancel_job` method: - -```py -arangoml.jobs.cancel_job(prediction_job.job_id) -``` - - -## Training - -**API Documentation: [ArangoML.jobs.train](https://arangoml.github.io/arangoml/api.html#agml_api.jobs.v1.api.jobs_api.JobsApi.train)** - -Training Graph Machine Learning Models with ArangoGraphML requires two steps: -1. Describe which data points should be included in the Training Job. -2. Pass the Training Specification to the Training Service. - -**The Training Service depends on a `Training Specification` that contains**: -- `featureSetID`: The feature set ID that was generated during the Featurization Job (if any). It replaces the need to provide the `metagraph`, `databaseName`, and `projectName` fields. - -- `databaseName`: The database name the source data is in. Can be omitted if `featureSetID` is provided. - -- `projectName`: The top-level project to which all the experiments will link back. Can be omitted if `featureSetID` is provided. - -- `useFeatureStore`: Boolean for enabling or disabling the use of the feature store. Default is `false`. - -- `mlSpec`: Describes the desired machine learning task, input features, and - the attribute label to be predicted. - - `classification`: Dictionary to describe the Node Classification Task Specification. - - `targetCollection`: The ArangoDB collection name that contains the prediction label. - - `inputFeatures`: The name of the feature to be used as input. - - `labelField`: The name of the attribute to be predicted. - - `batchSize`: The number of documents to process in a single training batch. Default is `64`. - - `graphEmbeddings`: Dictionary to describe the Graph Embedding Task Specification. - - `targetCollection`: The ArangoDB collection used to generate the embeddings. - - `embeddingSize`: The size of the embedding vector. Default is `128`. - - `batchSize`: The number of documents to process in a single training batch. Default is `64`. - - `generateEmbeddings`: Whether to generate embeddings on the training dataset. Default is `false`. - -- `metagraph`: Metadata to represent the vertex & edge collections of the graph. If `featureSetID` is provided, this can be omitted. - - `graph`: The ArangoDB graph name. - - `vertexCollections`: A dictionary mapping the collection names to the following values: - - `x`: The name of the feature to be used as input. - - `y`: The name of the attribute to be predicted. Can only be specified for one collection. - - `edgeCollections`: A dictionary mapping the edge collection names to an empty dictionary, as edge features are not currently supported. - -A Training Specification allows for concisely defining your training task in a -single object and then passing that object to the training service using the -Python API client, as shown below. - -The ArangoGraphML Training Service is responsible for training a series of -Graph Machine Learning Models using the data provided in the Training -Specification. It assumes that the data has been featurized and is ready to be -used for training. - -Given that we have run a Featurization Job, we can create the Training Specification using the `featurization_job_result` object returned from the Featurization Job: - -```py -# 1. Define the Training Specification - -# Node Classification example - -training_spec = { - "featureSetID": featurization_job_result.result.feature_set_id, - "mlSpec": { - "classification": { - "targetCollection": "Event", - "inputFeatures": "OPEN_INTELLIGENCE_ANGOLA_x", - "labelField": "OPEN_INTELLIGENCE_ANGOLA_y", - } - }, -} - -# Node Embedding example -# NOTE: Full Graph Embeddings support is coming soon - -training_spec = { - "featureSetID": featurization_job_result.result.feature_set_id, - "mlSpec": { - "graphEmbeddings": { - "targetCollection": "Event", - "embeddingSize": 128, - "generateEmbeddings": True, - } - }, -} -``` - -Once the specification has been defined, a Training Job can be triggered using the `arangoml.jobs.train` method: - -```py -# 2. Submit a Training Job - -training_job = arangoml.jobs.train(training_spec) -``` - -Once a Training Job has been submitted, you can wait for it to complete using the `arangoml.wait_for_training` method: - -```py -# 3. Wait for the Training Job to complete - -training_job_result = arangoml.wait_for_training(training_job.job_id) -``` - -**Example Output (Node Classification):** -```py -{ - "job_id": "691ceb2f-1931-492a-b4eb-0536925a4697", - "job_status": "COMPLETED", - "project_name": "OPEN_INTELLIGENCE_ANGOLA_GraphML_Node_Classification", - "project_id": "16832427", - "database_name": "OPEN_INTELLIGENCE_ANGOLA", - "metagraph": { - "mlSpec": { - "classification": { - "targetCollection": "Event", - "inputFeatures": "OPEN_INTELLIGENCE_ANGOLA_x", - "labelField": "OPEN_INTELLIGENCE_ANGOLA_y", - "metrics": None - } - }, - "graph": "OPEN_INTELLIGENCE_ANGOLA", - "vertexCollections": { - "Actor": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Class": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Country": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Event": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x", - "y": "OPEN_INTELLIGENCE_ANGOLA_y" - }, - "Source": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Location": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Region": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - } - }, - "edgeCollections": { - "eventActor": {}, - "hasSource": {}, - "hasLocation": {}, - "inCountry": {}, - "inRegion": {}, - "subClass": {}, - "type": {} - }, - "batch_size": 64 - }, - "time_submitted": "2024-01-12T02:19:19.686286", - "time_started": "2024-01-12T02:19:29.403742", - "time_ended": "2024-01-12T02:30:59.313038", - "job_state": None, - "job_conditions": None -} -``` - -**Example Output (Node Embeddings):** -```py -{ - "job_id": "6047e53a-f1dd-4725-83e8-74ac44629c11", - "job_status": "COMPLETED", - "project_name": "OPEN_INTELLIGENCE_ANGOLA_GraphML_Node_Embeddings", - "project_id": "647025872", - "database_name": "OPEN_INTELLIGENCE_ANGOLA", - "ml_spec": { - "graphEmbeddings": { - "targetCollection": "Event", - "embeddingLevel": "NODE_EMBEDDINGS", - "embeddingSize": 128, - "embeddingTrainingType": "UNSUPERVISED", - "batchSize": 64, - "generateEmbeddings": true, - "bestModelSelection": "BEST_LOSS", - "persistModels": "ALL_MODELS", - "modelConfigurations": {} - } - }, - "metagraph": { - "graph": "OPEN_INTELLIGENCE_ANGOLA", - "vertexCollections": { - "Actor": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Country": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Event": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x", - "y": "OPEN_INTELLIGENCE_ANGOLA_y" - }, - "Source": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Location": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - }, - "Region": { - "x": "OPEN_INTELLIGENCE_ANGOLA_x" - } - }, - "edgeCollections": { - "eventActor": {}, - "hasSource": {}, - "hasLocation": {}, - "inCountry": {}, - "inRegion": {} - } - }, - "time_submitted": "2025-03-27T02:55:15.099680", - "time_started": "2025-03-27T02:57:25.143948", - "time_ended": "2025-03-27T03:01:24.619737", - "training_type": "Training" -} -``` - -You can also cancel a Training Job using the `arangoml.jobs.cancel_job` method: - -```py -arangoml.jobs.cancel_job(training_job.job_id) -``` - -## Model Selection - -Model Statistics can be observed upon completion of a Training Job. -To select a Model, the ArangoGraphML Projects Service can be used to gather -all relevant models and choose the preferred model for a Prediction Job. - -First, let's list all the trained models using [ArangoML.list_models](https://arangoml.github.io/arangoml/client.html#arangoml.main.ArangoML.list_models): - -```py -# 1. List all trained Models - -models = arangoml.list_models( - project_name=project.name, - training_job_id=training_job.job_id -) - -print(len(models)) -``` - -The cell below selects the model with the highest **test accuracy** using [ArangoML.get_best_model](https://arangoml.github.io/arangoml/client.html#arangoml.main.ArangoML.get_best_model), but there may be other factors that motivate you to choose another model. See the `model_statistics` in the output field below for more information on the full list of available metrics. - -```py - -# 2. Select the best Model - -# Get best Node Classification Model -# Sort by highest test accuracy - -best_model = arangoml.get_best_model( - project.name, - training_job.job_id, - sort_parent_key="test", - sort_child_key="accuracy", -) - -# Get best Graph Embedding Model -# Sort by lowest loss - -best_model = arangoml.get_best_model( - project.name, - training_job.job_id, - sort_parent_key="loss", - sort_child_key=None, - reverse=False -) - -print(best_model) -``` - -**Example Output (Node Classification):** -```py -{ - "job_id": "691ceb2f-1931-492a-b4eb-0536925a4697", - "model_id": "02297435-3394-4e7e-aaac-82e1d224f85c", - "model_statistics": { - "_id": "devperf/123", - "_key": "123", - "_rev": "_gkUc8By--_", - "run_id": "123", - "test": { - "accuracy": 0.8891242216547955, - "confusion_matrix": [[13271, 2092], [1276, 5684]], - "f1": 0.9, - "loss": 0.1, - "precision": 0.9, - "recall": 0.8, - "roc_auc": 0.8, - }, - "validation": { - "accuracy": 0.9, - "confusion_matrix": [[13271, 2092], [1276, 5684]], - "f1": 0.85, - "loss": 0.1, - "precision": 0.86, - "recall": 0.85, - "roc_auc": 0.85, - }, - }, - "target_collection": "Event", - "target_field": "label", -} -``` - -**Example Output (Node Embeddings):** -```py -{ - "job_id": "6047e53a-f1dd-4725-83e8-74ac44629c11", - "model_id": "55ae93c2-3497-4405-9c63-0fa0e4a5b5bd", - "model_display_name": "graphsageencdec Model", - "model_name": "graphsageencdec Model 55ae93c2-3497-4405-9c63-0fa0e4a5b5bd", - "model_statistics": { - "loss": 0.13700408464796796, - "val_acc": 0.5795393939393939, - "test_acc": 0.5809545454545455 - }, - "model_tasks": [ "GRAPH_EMBEDDINGS" ] -} -``` - -## Prediction - -**API Documentation: [ArangoML.jobs.predict](https://arangoml.github.io/arangoml/api.html#agml_api.jobs.v1.api.jobs_api.JobsApi.predict)** - -Final step! - -After selecting a model, a Prediction Job can be created. The Prediction Job -will generate predictions and persist them to the source graph in a new -collection, or within the source documents. - -**The Prediction Service depends on a `Prediction Specification` that contains**: -- `projectName`: The top-level project to which all the experiments will link back. -- `databaseName`: The database name the source data is in. -- `modelID`: The model ID to use for generating predictions. -- `featurizeNewDocuments`: Boolean for enabling or disabling the featurization of new documents. Useful if you don't want to re-train the model upon new data. Default is `false`. -- `featurizeOutdatedDocuments`: Boolean for enabling or disabling the featurization of outdated documents. Outdated documents are those whose features have changed since the last featurization. Default is `false`. -- `schedule`: A cron expression to schedule the prediction job (e.g `0 0 * * *` for daily predictions). Default is `None`. -- `embeddingsField`: The name of the field to store the generated embeddings. This is only used for Graph Embedding tasks. Default is `None`. - -```py -# 1. Define the Prediction Specification - -# Node Classification Example -prediction_spec = { - "projectName": project.name, - "databaseName": dataset_db.name, - "modelID": best_model.model_id, -} - -# Node Embedding Example -prediction_spec = { - "projectName": project.name, - "databaseName": dataset_db.name, - "modelID": best_model.model_id, - "embeddingsField": "embeddings" -} -``` - -This job updates all documents with the predictions derived from the trained model. -Once the specification has been defined, a Prediction Job can be triggered using the `arangoml.jobs.predict` method: - -```py -# 2. Submit a Prediction Job - -# For Node Classification -prediction_job = arangoml.jobs.predict(prediction_spec) - -# For Graph Embeddings -prediction_job = arangoml.jobs.generate(prediction_spec) -``` - -Similar to the Training Service, we can wait for a Prediction Job to complete with the `arangoml.wait_for_prediction` method: - -```py -# 3. Wait for the Prediction Job to complete - -prediction_job_result = arangoml.wait_for_prediction(prediction_job.job_id) -``` - -**Example Output (Node Classification):** -```py -{ - "job_id": "b2a422bb-5650-4fbc-ba6b-0578af0049d9", - "job_status": "COMPLETED", - "project_name": "OPEN_INTELLIGENCE_ANGOLA_GraphML_Node_Classification", - "project_id": "16832427", - "database_name": "OPEN_INTELLIGENCE_ANGOLA", - "model_id": "1a365657-f5ed-4da9-948b-1ff60bc6e7de", - "job_state_information": { - "outputGraphName": "OPEN_INTELLIGENCE_ANGOLA", - "outputCollectionName": "Event", - "outputAttribute": "OPEN_INTELLIGENCE_ANGOLA_y_predicted", - "numberOfPredictedDocuments": 3302, - "outputEdgeCollectionName": None - }, - "time_submitted": "2024-01-12T02:31:18.382625", - "time_started": "2024-01-12T02:31:23.550469", - "time_ended": "2024-01-12T02:31:40.021035" -} -``` - -**Example Output (Node Embeddings):** -```py -{ - "job_id": "25260362-9764-47d0-abb4-247cbdce6c7b", - "job_status": "COMPLETED", - "project_name": "OPEN_INTELLIGENCE_ANGOLA_GraphML_Node_Embeddings", - "project_id": "647025872", - "database_name": "OPEN_INTELLIGENCE_ANGOLA", - "model_id": "55ae93c2-3497-4405-9c63-0fa0e4a5b5bd", - "job_state_information": { - "outputGraphName": "OPEN_INTELLIGENCE_ANGOLA", - "outputCollectionName": "Event", - "outputAttribute": "embeddings", - "numberOfPredictedDocuments": 0, # 0 All documents already have up-to-date embeddings - }, - "time_submitted": "2025-03-27T14:02:33.094191", - "time_started": "2025-03-27T14:09:34.206659", - "time_ended": "2025-03-27T14:09:35.791630", - "prediction_type": "Prediction" -} -``` - -You can also cancel a Prediction Job using the `arangoml.jobs.cancel_job` method: - -```py -arangoml.jobs.cancel_job(prediction_job.job_id) -``` - -### Viewing Inference Results - -We can now access our results via AQL: - -```py -import json - -collection_name = prediction_job_result.job_state_information['outputCollectionName'] - -query = f""" - FOR doc IN `{collection_name}` - SORT RAND() - LIMIT 3 - RETURN doc -""" - -docs = list(dataset_db.aql.execute(query)) - -print(json.dumps(docs, indent=2)) -``` - -## What's next - -With the generated Feature (and optionally Node) Embeddings, you can now use them for downstream tasks like clustering, anomaly detection, and link prediction. Consider using [ArangoDB's Vector Search](https://arangodb.com/2024/11/vector-search-in-arangodb-practical-insights-and-hands-on-examples/) capabilities to find similar nodes based on their embeddings. From 66d5571936b8b0a0ac82ce809d1f721148be08f2 Mon Sep 17 00:00:00 2001 From: Paula Date: Mon, 7 Jul 2025 16:29:58 +0200 Subject: [PATCH 13/16] rework graph rag main page --- .../3.13/data-science/graphrag/_index.md | 103 ++++++++++++++---- 1 file changed, 81 insertions(+), 22 deletions(-) diff --git a/site/content/3.13/data-science/graphrag/_index.md b/site/content/3.13/data-science/graphrag/_index.md index 712cb9c0b2..9f032428a4 100644 --- a/site/content/3.13/data-science/graphrag/_index.md +++ b/site/content/3.13/data-science/graphrag/_index.md @@ -4,11 +4,13 @@ menuTitle: GraphRAG weight: 10 description: >- ArangoDB's GraphRAG solution combines graph-based retrieval augmented generation - with Large Language Models (LLMs) for turbocharged Gen AI solutions + with Large Language Models (LLMs) for turbocharged GenAI solutions aliases: llm-knowledge-graphs -# TODO: Repurpose for GenAI --- + +## Introduction + Large language models (LLMs) and knowledge graphs are two prominent and contrasting concepts, each possessing unique characteristics and functionalities that significantly impact the methods we employ to extract valuable insights from @@ -30,16 +32,10 @@ LLMs provide a powerful and efficient solution for anyone seeking to extract valuable insights from diverse datasets. The GraphRAG component of the GenAI Suite brings all the capabilities -together with an easy-to-use interface so you can make the knowledge accessible +together with an easy-to-use interface, so you can make the knowledge accessible to your organization. -## ArangoDB GraphRAG - -ArangoDB's GraphRAG 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 +## 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. @@ -60,22 +56,85 @@ the following tasks: - End-to-end knowledge graph construction - (Text) Embeddings +## How GraphRAG works + +ArangoDB's GraphRAG solution democratizes the creation and usage of knowledge +graphs with a unique combination of vector search, graphs, and LLMs in a +single product. + +The overall process of GraphRAG involves: +- **Creating a Knowledge Graph** from raw text data. +- **Identifying and extract entities, relationships, and their connections** within the data. +- **Storing the structured information** in ArangoDB. +- **Using this structured representation** as the foundation for efficient and accurate information retrieval. +- **Integrating retrieval methods with LLMs** to augment responses using both structured and unstructured data. +- **Enhancing the reliability and depth** of responses by combining these approaches. + +GraphRAG is particularly valuable for: +- Applications requiring in-depth knowledge retrieval +- Contextual question answering, +- Reasoning over interconnected information + ![ArangoDB Knowledge Graphs and LLMs](../../../images/ArangoDB-knowledge-graphs-meets-llms.png) -### Examples +### Turn text files into a Knowledge Graph + +The RagLoader service is the entry point of the GraphRAG pipeline. It takes a +raw text file as input, processes it using an LLM to extract entities and +relationships, and generates a Knowledge Graph. The Knowledge Graph is then +stored in an ArangoDB database for further use. The Knowledge Graph represents +information in a structured graph format, allowing efficient querying and retrieval. + +1. Pre-process the raw text file to identify entities and their relationships. +2. Use LLMs to infer connections and context, enriching the Knowledge Graph. +3. Store the generated Knowledge Graph in the database for retrieval and reasoning. + +For detailed information about the service, see the +[RagLoader](./services/rag-loader.md) documentation. + +### Extract information from the Knowledge Graph + +The RagRetriever service enables intelligent search and retrieval of information +from your previously created Knowledge Graph. +You can extract information from Knowledge Graphs using two distinct methods: +- Global retrieval +- Local retrieval + +For detailed information about the service, see the +[RagRetriever](./services/rag-retriever.md) documentation. + +#### Global retrieval + +Global retrieval focuses on: +- Extracting information from the entire Knowledge Graph, regardless of specific + contexts or constraints. +- Provides a comprehensive overview and answers queries that span across multiple + entities and relationships in the graph. + +**Use cases:** +- Answering broad questions that require a holistic understanding of the Knowledge Graph. +- Aggregating information from diverse parts of the Knowledge Graph for high-level insights. + +**Example query:** + +Global retrieval can answer questions like _**What are the main themes or topics covered in the document**_? + +This would involve analyzing the entire KG to identify and summarize the dominant entities, their relationships, and associated themes. + +#### Local retrieval -### Interfaces +Local retrieval is a more focused approach for: +- Queries that are constrained to specific subgraphs or contextual clusters + within the Knowledge Graph. +- Targeted and precise information extraction, often using localized sections + of the Knowledge Graph. -{{< tabs "interfaces" >}} +**Use cases:** +- Answering detailed questions about a specific entity or a related group of entities. +- Retrieving information relevant to a particular topic or section in the Knowledge Graph. -{{< tab "Web interface" >}} -1. In the Platform UI, ... -{{< /tab >}} +**Example query:** -{{< tab "cURL" >}} -``` -curl http://localhost:8529/gen-ai/ -``` -{{< /tab >}} +Local retrieval can answer questions like _**What is the relationship between entity X and entity Y**_? -{{< /tabs >}} +This query focuses only on the subgraph involving entities X and Y, extracting detailed relationships and context. From 1fdc37e99cbaed2c0528fef5a74947036ac33790 Mon Sep 17 00:00:00 2001 From: Paula Date: Tue, 8 Jul 2025 15:40:24 +0200 Subject: [PATCH 14/16] formatting --- .../data-science/graphrag/services/gen-ai.md | 58 +++-- .../data-science/graphrag/services/mlflow.md | 67 ++++-- .../graphrag/services/rag-loader.md | 211 +++++++++++------- 3 files changed, 212 insertions(+), 124 deletions(-) diff --git a/site/content/3.13/data-science/graphrag/services/gen-ai.md b/site/content/3.13/data-science/graphrag/services/gen-ai.md index 8f13367645..148f574398 100644 --- a/site/content/3.13/data-science/graphrag/services/gen-ai.md +++ b/site/content/3.13/data-science/graphrag/services/gen-ai.md @@ -7,23 +7,26 @@ description: >- # TODO: Shouldn't this refer to the ArangoDB Platform instead? weight: 5 --- -## Description The basic operations that the GenAI orchestration service carries out are the following: - Install a service - Uninstall a service - Get the status of a service -Each unique service does have its own API endpoint for the deployment. +Each unique service has its own API endpoint for the deployment. **Endpoint LLM Host:** `https://:8529/gen-ai/v1/llmhost` -While they have their own unique endpoint, all services share the same creation request body and the same response body structure. While the env field is used to define the service specific parameters, like e.g. the model name to use for a llm host service, the labels can be used to filter and identify the services in the platform. All services do support the 'profiles' field, which can be used to define the profile to use for the service. One use case is defining a GPU profile that enables the service to run an LLM on GPU resources. +While services have their own unique endpoint, they share the same creation +request body and the same response body structure. The `env` field is used +to define the service specific parameters, like the model name to use for a +`llmhost` service, and the labels can be used to filter and identify the services +in the platform. All services support the `profiles` field, which you can use +to define the profile to use for the service. For example, you can define a +GPU profile that enables the service to run an LLM on GPU resources. -## Examples - -### LLM Host Service Creation Request Body +## LLM Host Service Creation Request Body ```json { @@ -33,7 +36,7 @@ While they have their own unique endpoint, all services share the same creation } ``` -### Using Labels in Creation Request Body +## Using Labels in Creation Request Body ```json { @@ -46,10 +49,13 @@ While they have their own unique endpoint, all services share the same creation } } ``` +{{< info >}} +Labels are optional. Labels can be used to filter and identify services in +the platform. If you want to use labels, define them as a key-value pair in `labels` +within the `env` field. +{{< /info >}} -**Note:** Labels are optional. Labels can be used to filter and identify services in the platform. If you want to use labels, define them as a key-value pair in the `labels` within the `env` field. - -### Using Profiles in Creation Request Body +## Using Profiles in Creation Request Body ```json { @@ -60,24 +66,34 @@ While they have their own unique endpoint, all services share the same creation } ``` -**Note:** The `profiles` field is optional. If it is not set, the service will be created with the default profile. Profiles must be present and created in the platform before they can be used. If you want to use profiles, define them as a comma-separated string in the `profiles` within the `env` field. +{{< info >}} +The `profiles` field is optional. If it is not set, the service is created with +the default profile. Profiles must be present and created in the platform before +they can be used. If you want to use profiles, define them as a comma-separated +string in `profiles` within the `env` field. +{{< /info >}} -The service specific required parameters for the deployment are defined in the corresponding service documentation. +The service specific required parameters for the deployment are defined in the +corresponding service documentation. ## Obtaining a Bearer Token -Before you can authenticate with the GenAI service, you need to obtain a Bearer token. You can generate this token using the ArangoDB authentication API: +Before you can authenticate with the GenAI service, you need to obtain a +Bearer token. You can generate this token using the ArangoDB authentication API: ```bash curl -X POST https://:8529/_open/auth \ -d '{"username": "your-username", "password": "your-password"}' ``` -This will return a JWT token that you can use as your Bearer token. For more details about ArangoDB authentication and JWT tokens, see the [ArangoDB Authentication Documentation](https://docs.arangodb.com/stable/develop/http-api/authentication/#jwt-user-tokens). +This returns a JWT token that you can use as your Bearer token. For more +details about ArangoDB authentication and JWT tokens, see +the [ArangoDB Authentication](https://docs.arangodb.com/stable/develop/http-api/authentication/#jwt-user-tokens) +documentation. ## Complete Service Lifecycle Example -Here's a complete example showing how to install, monitor, and uninstall a RAGLoader service: +The example below shows how to install, monitor, and uninstall a RAGLoader service. ### Step 1: Install the Service @@ -146,10 +162,10 @@ curl -X DELETE https://:8529/gen-ai/v1/service/arangodb-graphr } ``` -**Notes:** - +{{< info >}} - **Service ID**: The `serviceId` from Step 1's response (`arangodb-graphrag-importer-of1ml`) is used in Steps 2 and 3 - **Authentication**: All requests use the same Bearer token in the `Authorization` header +{{< /info >}} ### Customizing the Example @@ -178,8 +194,12 @@ curl -X GET https://:8529/gen-ai/v1/health Expected output on success: `{"status":"OK"}` -**Note:** Keep in mind that this request requires a valid Bearer token. Without a valid Bearer token, the request will fail. +{{< info >}} +Keep in mind that this request requires a valid Bearer token. Without a valid +Bearer token, the request fails. +{{< /info >}} ## API Reference -For detailed API documentation, visit: [GenAI-Service API Reference](https://arangoml.github.io/platform-dss-api/GenAI-Service/proto/index.html) +For detailed API documentation, see the +[GenAI-Service API Reference](https://arangoml.github.io/platform-dss-api/GenAI-Service/proto/index.html). diff --git a/site/content/3.13/data-science/graphrag/services/mlflow.md b/site/content/3.13/data-science/graphrag/services/mlflow.md index 3b0dabb30e..e8e3900e77 100644 --- a/site/content/3.13/data-science/graphrag/services/mlflow.md +++ b/site/content/3.13/data-science/graphrag/services/mlflow.md @@ -8,35 +8,49 @@ weight: 25 --- ## Overview -The ArangoDB MLflow service is a service that hosts the official MLflow application in your Kubernetes cluster and connects it automatically to the ArangoDB environment, e.g. for registering the LLM to be self-hosted and used by services requiring LLMs (natural-language-service, RAGLoader, RAGRetriever). - -MLflow is an open-source platform, purpose-built to assist machine learning practitioners and teams in handling the complexities of the machine learning process. It focuses on the full lifecycle for machine learning projects, ensuring that each phase is manageable, traceable, and reproducible. - -The main purpose of our MLflow integration is to provide a seamless experience for users to manage their machine learning models and experiments within the ArangoDB environment. For example, any spawned LLM host service will automatically be linked to the MLflow service and will be able to fetch any registered model from the MLflow model registry. - -**Note:** The detailed instructions about how to organize the format of a model for the dedicated LLM host service can be found in their respective documentation. - -## Core Components +The ArangoDB MLflow service is a service that hosts the official MLflow +application in your Kubernetes cluster and connects automatically to the +ArangoDB environment, e.g. for registering the LLM to be self-hosted and +used by services requiring LLMs (Natural language service, RAGLoader, RAGRetriever). + +MLflow is an open-source platform, purpose-built to assist machine learning +practitioners and teams in handling the complexities of the machine learning +process. It focuses on the full lifecycle for machine learning projects, ensuring +that each phase is manageable, traceable, and reproducible. + +The main purpose of the ArangoDB's MLflow integration is to provide a seamless +experience to manage your machine learning models and experiments within the +ArangoDB environment. For example, any spawned LLM host service is automatically +linked to the MLflow service and is able to fetch any registered model from the +MLflow model registry. + +{{< info >}} +You can find detailed instructions about how to organize the format of a model for a +dedicated LLM host service in the official [MLflow](https://mlflow.org/docs/latest/genai/) +documentation. +{{< /info >}} + +## Core components MLflow consists of the following core components: -- **Model Registry**: A centralized model store, set of APIs, and UI to collaboratively manage the full lifecycle of an MLflow Model, including model lineage, versioning, stage transitions, and annotations. - -- **Experiment Tracking**: Provides an API and UI for logging parameters, code versions, metrics, and artifacts during the ML process, allowing for comparison of multiple runs across different users. - +- **Model Registry**: A centralized model store, set of APIs, and UI to + collaboratively manage the full lifecycle of an MLflow Model, including + model lineage, versioning, stage transitions, and annotations. +- **Experiment Tracking**: Provides an API and UI for logging parameters, + code versions, metrics, and artifacts during the ML process, allowing + for comparison of multiple runs across different users. - **Model Packaging**: Offers a standard format for packaging models from any framework. - -- **Serving**: Facilitates the deployment of models to various platforms. Within the ArangoDB environment, this enables the integration with services that utilize self-hosted LLMs. - +- **Serving**: Facilitates the deployment of models to various platforms. + Within the ArangoDB environment, this enables the integration with services that utilize self-hosted LLMs. - **Evaluation**: Provides tools for in-depth model analysis, facilitating objective model comparison. - - **Observability**: Ensures that the ML lifecycle is traceable and reproducible through various metrics and logs. ## Getting Started The ArangoDB MLflow service is **started by default**. -It will be automatically spawned and available at the following URL: +It is automatically spawned and available at the following URL: ``` https://:8529/mlflow/ @@ -48,18 +62,25 @@ You can interact with the ArangoDB MLflow service in two ways: To use the programmatic API, please use the **official MLflow client**. -**Note:** The ArangoDB MLflow service requires authentication. You need a valid Bearer token to access the service. +{{< info >}} +The ArangoDB MLflow service requires authentication. You need a valid +Bearer token to access the service. +{{< /info >}} #### Obtaining a Bearer Token -Before you can authenticate with the MLflow service, you need to obtain a Bearer token. You can generate this token using the ArangoDB authentication API: +Before you can authenticate with the MLflow service, you need to obtain a +Bearer token. You can generate this token using the ArangoDB authentication API: ```bash curl -X POST https://:8529/_open/auth \ -d '{"username": "your-username", "password": "your-password"}' ``` -This will return a JWT token that you can use as your Bearer token. For more details about ArangoDB authentication and JWT tokens, see the [ArangoDB Authentication Documentation](https://docs.arangodb.com/stable/develop/http-api/authentication/#jwt-user-tokens). +This returns a JWT token that you can use as your Bearer token. +For more details about ArangoDB authentication and JWT tokens, see the +[ArangoDB Authentication](https://docs.arangodb.com/stable/develop/http-api/authentication/#jwt-user-tokens) +documentation. ### Installation @@ -119,8 +140,8 @@ Expected output on success: HTTP `200` status with response body `OK` ## API Reference -For detailed API documentation, refer to the official MLflow REST API documentation: -[MLflow REST API Reference](https://mlflow.org/docs/latest/api_reference/rest-api.html) +For detailed API documentation, refer to the official +[MLflow REST API Reference](https://mlflow.org/docs/latest/api_reference/rest-api.html). ## Additional Resources diff --git a/site/content/3.13/data-science/graphrag/services/rag-loader.md b/site/content/3.13/data-science/graphrag/services/rag-loader.md index eb94d7a457..afe557b2a1 100644 --- a/site/content/3.13/data-science/graphrag/services/rag-loader.md +++ b/site/content/3.13/data-science/graphrag/services/rag-loader.md @@ -2,7 +2,7 @@ title: RagLoader Service menuTitle: RagLoader description: >- - The RagLoader service helps you transform your text document into knowledge graph, + The RagLoader service helps you transform your text document into a knowledge graph, making it easier to analyze and understand complex information weight: 10 --- @@ -13,109 +13,145 @@ It supports the following text formats with UTF-8 encoding: - Plain text - Markdown -The Loader takes your text, analyzes it using the configured language model, and +The RagLoader 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. +different concepts in your document with the RagRetriever service. -## How ArangoDB Collections looks after Import Process: +## How ArangoDB collections look like -The RagLoader creates several collections in ArangoDB to store different aspects of your knowledge graph. Here's a detailed explanation of each collection: +The RagLoader creates several collections in ArangoDB to store different +aspects of your knowledge graph. See below a detailed explanation of each +collection. -### Documents Collection -- **Purpose**: Stores the original text document that were processed +### 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 + - `_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 + +- **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 + - `_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 + - `_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. + +- **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. + - `_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 + - `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 (the 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 + - 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 + +- **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") + - `_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 + - `weight`: Relationship strength (the 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 +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: +## 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. +### Private LLM -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. +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 your 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. +### Public LLM -### How to install RagLoader Service +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. -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. + +## Installation + +The RagLoader service can be configured to use either: +- Triton Inference Server (for private LLM deployments) +- OpenAI (for public LLM deployments) +- OpenRouter (for public LLM deployments) + +To start the service, use the GenAI service endpoint `/v1/graphragimporter`. +Please refer to the documentation of [GenAI service](gen-ai.md) 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) +### 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: +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 loader service using the below reference: @@ -132,13 +168,14 @@ Once the LLM-host service is installed and running successfully, then you can st } ``` +Where: - `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 +### Using OpenAI (Public LLM) ```json { @@ -151,19 +188,26 @@ Once the LLM-host service is installed and running successfully, then you can st } ``` +Where: - `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. - +{{< info >}} +By default, for OpenAI API, the service is using +`gpt-4o-mini` and `text-embedding-3-small` models as LLM and +embedding model respectively. +{{< /info >}} ### 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. +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. +When using the OpenRouter option, the LLM responses are served via OpenRouter +while OpenAI is used for the embedding model. ```json { @@ -178,6 +222,7 @@ When using the OpenRouter option, the LLM responses are served via OpenRouter wh } ``` +Where: - `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 @@ -185,14 +230,17 @@ When using the OpenRouter option, the LLM responses are served via OpenRouter wh - `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 +{{< info >}} +When using OpenRouter, the service defaults to `mistral-nemo` for generation +(via OpenRouter) and `text-embedding-3-small` for embeddings (via OpenAI). +{{< /info >}} -Once service is installed successfully, you can follow the following steps to send an input file to the loader service: +## Building Knowledge Graphs -1. Prepare your text document for processing (text format with UTF-8 encoding or markdown files) +Once the 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 @@ -208,23 +256,22 @@ Once service is installed successfully, you can follow the following steps to se ``` Replace the following placeholders: - - ``: Your ArangoDB Platform URL - - ``: The URL postfix configured in your deployment + - ``: 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 - + - 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 +### 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 +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. + - `knowledge_graph_edges`: Contains the relationships between nodes i.e. relations. \ No newline at end of file From e0a2f62834f975ab54a1467d1d62df5776d407f1 Mon Sep 17 00:00:00 2001 From: Paula Date: Tue, 8 Jul 2025 16:33:13 +0200 Subject: [PATCH 15/16] more formatting --- .../data-science/graphrag/services/mlflow.md | 21 +-- .../graphrag/services/rag-loader.md | 1 - .../graphrag/services/rag-retriever.md | 176 ++++++++++-------- 3 files changed, 108 insertions(+), 90 deletions(-) diff --git a/site/content/3.13/data-science/graphrag/services/mlflow.md b/site/content/3.13/data-science/graphrag/services/mlflow.md index e8e3900e77..ba8167a950 100644 --- a/site/content/3.13/data-science/graphrag/services/mlflow.md +++ b/site/content/3.13/data-science/graphrag/services/mlflow.md @@ -26,7 +26,7 @@ MLflow model registry. {{< info >}} You can find detailed instructions about how to organize the format of a model for a -dedicated LLM host service in the official [MLflow](https://mlflow.org/docs/latest/genai/) +dedicated LLM host service in the official [MLflow]((https://mlflow.org/docs/latest/index.html) documentation. {{< /info >}} @@ -46,7 +46,7 @@ MLflow consists of the following core components: - **Evaluation**: Provides tools for in-depth model analysis, facilitating objective model comparison. - **Observability**: Ensures that the ML lifecycle is traceable and reproducible through various metrics and logs. -## Getting Started +## Quickstart The ArangoDB MLflow service is **started by default**. @@ -90,11 +90,11 @@ First, install the MLflow client: pip install mlflow ``` -### Programmatic Access +### Programmatic access -There are two approaches for programmatic access to your ArangoDB MLflow service: +There are two approaches for programmatic access to your ArangoDB MLflow service. -#### Approach 1: Configure in Python Code +#### Configuration in Python ```python import mlflow @@ -109,7 +109,7 @@ with mlflow.start_run(): mlflow.log_artifact("local_file.txt") ``` -#### Approach 2: Use Environment Variables +#### Using environment variables Set the environment variables in your shell: @@ -128,7 +128,7 @@ with mlflow.start_run(): mlflow.log_artifact("local_file.txt") ``` -### Health Check +### Health check To test whether the service is running, you can use the following snippet: @@ -136,14 +136,9 @@ To test whether the service is running, you can use the following snippet: curl -H "Authorization: Bearer your-bearer-token-here" https://:8529/mlflow/health ``` -Expected output on success: HTTP `200` status with response body `OK` +Expected output on success: HTTP `200` status with response body `OK`. ## API Reference For detailed API documentation, refer to the official [MLflow REST API Reference](https://mlflow.org/docs/latest/api_reference/rest-api.html). - -## Additional Resources - -The official MLflow documentation can be found at: -[MLflow Documentation](https://mlflow.org/docs/latest/index.html) diff --git a/site/content/3.13/data-science/graphrag/services/rag-loader.md b/site/content/3.13/data-science/graphrag/services/rag-loader.md index afe557b2a1..ced8099440 100644 --- a/site/content/3.13/data-science/graphrag/services/rag-loader.md +++ b/site/content/3.13/data-science/graphrag/services/rag-loader.md @@ -147,7 +147,6 @@ The RagLoader service can be configured to use either: To start the service, use the GenAI service endpoint `/v1/graphragimporter`. Please refer to the documentation of [GenAI service](gen-ai.md) for more information on how to use it. -Here are the configuration options for all three options: ### Using Triton Inference Server (Private LLM) diff --git a/site/content/3.13/data-science/graphrag/services/rag-retriever.md b/site/content/3.13/data-science/graphrag/services/rag-retriever.md index 2b1064df77..2062c34047 100644 --- a/site/content/3.13/data-science/graphrag/services/rag-retriever.md +++ b/site/content/3.13/data-science/graphrag/services/rag-retriever.md @@ -3,74 +3,80 @@ title: RagRetriever Service menuTitle: RagRetriever description: >- RagRetriever is a powerful service that enables intelligent search and - retrieval from knowledge graphs created by the GraphRAG Importer -# TODO: GraphRAG Importer == RagLoader? + retrieval from knowledge graphs created by the RAGLoader weight: 15 --- -## Summary +## Overview The RagRetriever service 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. -- **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. +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: +**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 +## Search methods -### Global Search +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 RAGLoader +to deliver accurate and contextually relevant responses to your natural language queries. -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. +### Global search -#### How Global Search Works +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. -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 +- **Community-Based Analysis**: Uses pre-generated community reports from your + knowledge graph to understand the overall structure and themes of your data, +- **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 +**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 -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. +Local search focuses on specific entities and their relationships within your +knowledge graph. It is ideal for detailed queries about particular concepts, +entities, or relationships. -#### How Local Search Works +- **Entity Identification**: Identifies relevant entities from the knowledge graph based on the query. +- **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. +- **Prioritized Response**: Generates a response using the most relevant gathered information. -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 +**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 +## Installation + +The RagRetriever service can be configured to use either the Triton Inference Server +(for private LLM deployments) or OpenAI/OpenRouter (for public LLM deployments). -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: +To start the service, use the GenAI service endpoint `/v1/graphragretriever`. +Please refer to the documentation of [GenAI service](gen-ai.md) for more +information on how to use it. ### Using Triton Inference Server (Private LLM) @@ -91,13 +97,14 @@ Once the LLM-host service is installed and running successfully, then you can st } ``` -- `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 +Where: +- `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 +### Using OpenAI (Public LLM) ```json { @@ -110,17 +117,26 @@ Once the LLM-host service is installed and running successfully, then you can st } ``` +Where: - `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. +{{< info >}} +By default, for OpenAI API, the service is using +`gpt-4o-mini` and `text-embedding-3-small` models as LLM and +embedding model respectively. +{{< /info >}} + ### 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. +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. +When using the OpenRouter option, the LLM responses are served via OpenRouter while +OpenAI is used for the embedding model. ```json { @@ -135,23 +151,27 @@ When using the OpenRouter option, the LLM responses are served via OpenRouter wh } ``` -- `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`) +Where: +- `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 +{{< info >}} +When using OpenRouter, the service defaults to `mistral-nemo` for generation +(via OpenRouter) and `text-embedding-3-small` for embeddings (via OpenAI). +{{< /info >}} -### Executing Queries +## Executing queries -After the retriever service is installed successfully. You can interact with the retriever service using the following HTTP endpoint: +After the RagRetriever service is installed successfully, you can interact with +it using the following HTTP endpoints, based on the selected search method. -#### Local Search +{{< tabs "executing-queries" >}} +{{< tab "Local search" >}} ```bash curl -X POST /v1/graphrag-query \ -H "Content-Type: application/json" \ @@ -161,8 +181,9 @@ curl -X POST /v1/graphrag-query \ "provider": 0 }' ``` +{{< /tab >}} -#### Global Search +{{< tab "Global search" >}} ```bash curl -X POST /v1/graphrag-query \ @@ -174,32 +195,35 @@ curl -X POST /v1/graphrag-query \ "provider": 0 }' ``` +{{< /tab >}} -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 +{{< /tabs >}} + +The request parameters are the following: +- `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 +## Health check + +You can also monitor the service health: -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 - +- **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 +- **Performance considerations**: + - Global search may take longer due to its map-reduce process. + - Local search is typically faster for concrete queries. \ No newline at end of file From f44021098d892fa12a60d4862d8961652cf107dd Mon Sep 17 00:00:00 2001 From: Paula Date: Tue, 8 Jul 2025 16:47:11 +0200 Subject: [PATCH 16/16] add initial docs for triton --- .../services/triton-inference-server.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 site/content/3.13/data-science/graphrag/services/triton-inference-server.md diff --git a/site/content/3.13/data-science/graphrag/services/triton-inference-server.md b/site/content/3.13/data-science/graphrag/services/triton-inference-server.md new file mode 100644 index 0000000000..1a332d4c53 --- /dev/null +++ b/site/content/3.13/data-science/graphrag/services/triton-inference-server.md @@ -0,0 +1,122 @@ +--- +title: Triton Inference Server +menuTitle: Triton Inference Server +description: >- + Private LLM using the Triton Inference Server +weight: 30 +--- + +## Overview + +The **LLM Host Triton** service provides scalable deployment of Large Language Models (LLMs) using NVIDIA Triton Inference Server. It enables efficient serving of machine learning models with support for HTTP/gRPC APIs, customizable routing, and seamless Kubernetes integration. + +## Service Deployment + +The service is deployed as a **Kubernetes application** using Helm charts in the ArangoDB platform ecosystem. It integrates with: +- MLFlow model registry for model management +- Storage sidecar for artifact storage + +## Installation via Gen-AI Service API + +To install the LLM Host Triton service, send an API request to the **gen-ai service** with the following parameters: + +### Required Parameters + +```json +{ + "models": "model_name@version,model_name2@version2", + + +} +``` + +### Optional Parameters + +```json +{ + "log_level": "INFO", + "profiles": "profile1,profile2" + "resources_requests_memory": "", // Minimum memory required for the container + "resources_requests_cpu": "", // Minimum CPU required for the container + "resources_limits_memory": "", // Maximum memory the container can use + "resources_limits_cpu": "", // Maximum CPU the container can use + "resources_requests_ephemeral_storage": "", // Minimum ephemeral storage required for the container + "resources_limits_ephemeral_storage": "" // Maximum ephemeral storage the container can use +} +``` + +### Parameter Descriptions + +| Parameter | Required | Description | Example | +|-----------|----------|-------------|---------| +| `models` | ✅ | Comma-separated list of model_name@version pairs | `"mistral@1,t5@3"` | +| `resources_requests_memory` | ❌ | Minimum memory required | `"8Gi"` | +| `resources_requests_cpu` | ❌ | Minimum CPU cores required | `"2"` | +| `resources_limits_memory` | ❌ | Maximum memory allowed | `"16Gi"` | +| `resources_limits_cpu` | ❌ | Maximum CPU cores allowed | `"4"` | +| `log_level` | ❌ | Logging level | `"INFO"` (default) | +| `profiles` | ❌ | Platform profiles to apply | `"gpu,performance"` | + +## Model Requirements + +### Python Backend Mandatory + +All models deployed on this service **must use the Python backend**. Each model requires: + +1. **`model.py`** - Python implementation with: + ```python + class TritonPythonModel: + def initialize(self, args): + # Load your model here + pass + + def execute(self, requests): + # Process inference requests + pass + + def finalize(self): + # Cleanup resources + pass + ``` + +2. **`config.pbtxt`** - Triton configuration: + ``` + name: "your_model_name" + backend: "python" + max_batch_size: 1 + input: [...] + output: [...] + ``` + +### Model Storage + +Models must be stored in the **MLFlow model registry** and will be automatically downloaded and loaded by the service. + +For detailed guidance on creating and uploading a python-backend model, refer to the [LLM Host Registry Services documentation](https://arangodb.atlassian.net/wiki/spaces/TUP/pages/2724757505/LLM+Host+Registry+Services). + +## Service Endpoints + +Once deployed, the service exposes two endpoints: + +| Port | Protocol | Purpose | +|------|----------|---------| +| 8000 | HTTP/REST | Model inference, management, status | +| 8001 | gRPC | High-performance binary communication | + +Triton Inference Server is not intended to be used in a standalone mode, but rather through other services +consuming these endpoints to send infer requests for example. So please refer to the service with which you are using Triton Inference Server for more details. + +Therefore, Triton service http endpoint can be accessed from inside the ArangoDB platform as follows: `https://{SERVICE_ID}.{KUBERNETES_NAMESPACE}.svc:8000`, +where KUBERNETES_NAMESPACE is the namespace of the ArangoDB platform and you can find it in an environment +variable called `KUBERNETES_NAMESPACE`. And SERVICE_ID is the ID of the LLM Host Triton service, which can be found in the `gen-ai service` response. For example, to check the server health, you need to send a GET request to `https://{SERVICE_ID}.{KUBERNETES_NAMESPACE}.svc:8000/v2/health/ready`. + +Similarly, you can access gRPC endpoints on port 8001, please refer to the official Triton documentation below for more details. + +From outside the ArangoDB platform, you can access the Triton Inference Server http endpoints using the following URL: `https://{BASE_URL}:8529/llm/{SERVICE_POSTFIX}/`, where BASE_URL is the base URL of the ArangoDB platform and service_postfix is the postfix of the LLM Host Triton service, it is the last 5 characters of the service ID. +For example, to check the server health from outside the platform, send a GET request to `https://{BASE_URL}:8529/llm/{SERVICE_POSTFIX}/v2/health/ready`. + +## Triton Inference Server Endpoints + +The service exposes all standard Triton Inference Server endpoints at port 8000 for http protocol or port 8001 for gRPC protocol for internal uage inside ArangoDB platform, and only http protocol is supported from outside the ArangoDB platform. This includes the following endpoints: model inference, model management, model status, and health check. + +For complete documentation on available endpoints and their usage, refer to the [Triton Inference Server HTTP API documentation](https://docs.nvidia.com/deeplearning/triton-inference-server/archives/triton_inference_server_1120/triton-inference-server-guide/docs/http_grpc_api.html#section-api-health). \ No newline at end of file