diff --git a/site/content/3.13/about-arangodb/features/_index.md b/site/content/3.13/about-arangodb/features/_index.md index a2db52724b..b1b00f00c5 100644 --- a/site/content/3.13/about-arangodb/features/_index.md +++ b/site/content/3.13/about-arangodb/features/_index.md @@ -21,6 +21,10 @@ aliases: See the full [Feature list of the ArangoDB core database system](core.md). +For a scalable architecture based on Kubernetes that supports the full offering +of ArangoDB including graph-powered machine learning and GenAI features, see +the [Feature list of the ArangoDB Platform](platform.md). + ## On-premises versus Cloud ### Fully managed cloud service diff --git a/site/content/3.13/about-arangodb/features/platform.md b/site/content/3.13/about-arangodb/features/platform.md new file mode 100644 index 0000000000..bdea671ffd --- /dev/null +++ b/site/content/3.13/about-arangodb/features/platform.md @@ -0,0 +1,54 @@ +--- +title: Feature list of the ArangoDB Platform +menuTitle: Platform +weight: 10 +description: >- + The ArangoDB Platform is a scalable architecture that gets you all features + of ArangoDB including graph-powered machine learning and GenAI as a single + solution with a unified interface +--- +For in-depth information about the ArangoDB Platform as a whole and how to +deploy and use it, see [The ArangoDB Platform](../../components/platform.md). + +## Architecture + +- **Core Database**: The ArangoDB database system forms the solid core + of the ArangoDB Platform. + +- **Kubernetes**: An open-source container orchestration system for automating + software deployment, scaling, and management designed by Google. + +- **Helm**: A package manager for Kubernetes that enables consistent, repeatable + installations and version control. + +- **Envoy**: A high-performance service proxy that acts as the gateway for the + ArangoDB Platform for centralizing authentication and routing. + +- **Web interface**: The Platform includes a unified, browser-based UI that lets + you access its features in an intuitive way. Optional products like the + GenAI Suite seamlessly integrate into the UI if installed. + +## Features + +- [**ArangoDB Core**](core.md): The ArangoDB database system with support for + graphs, documents, key-value, full-text search, and vector search. + +- [**Graph visualizer**](../../graphs/graph-visualizer.md): + A web-based tool for exploring your graph data with an intuitive interface and + sophisticated querying capabilities. + +- [**Graph Analytics**](../../graphs/graph-analytics.md): + A service that can efficiently load graph data from the core database system + and run graph algorithms such as PageRank. + +- [**GenAI Suite**](../../data-science/_index.md): + ArangoDB's GraphML and GraphRAG solutions for graph-powered machine learning + and GenAI applications. + +- [**Notebook servers**](../../data-science/notebook-servers.md): + Run Jupyter kernels in the Platform for hosting interactive, Python-based + notebooks to experiment and develop applications. + +- [**MLflow integration**](../../data-science/graphrag/services/mlflow.md): + Use the popular MLflow for machine learning practitioners as part of the + ArangoDB Platform. diff --git a/site/content/3.13/components/platform.md b/site/content/3.13/components/platform.md new file mode 100644 index 0000000000..a7e2e9328b --- /dev/null +++ b/site/content/3.13/components/platform.md @@ -0,0 +1,84 @@ +--- +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. +- **Helm**: A package manager for Kubernetes. It is used to install Platform + services with the correct versions. +- **Licenses**: If you want to use any paid features, you need to purchase the + respective packages. + +## Features of 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. +- **Graph Analytics**: A suite of graph algorithms including PageRank, + community detection, and centrality measures with support for GPU + acceleration thanks to Nvidia cuGraph. +- **GraphML**: A turnkey solution for graph machine learning for prediction + use cases such as fraud detection, supply chain, healthcare, retail, and + cyber security. +- **GenAI Suite**: A set of paid machine learning services, APIs, and + user interfaces that are available as a package as well as individual products. + - **GraphRAG**: Leverage ArangoDB's graph, document, key-value, + full-text search, and vector search features to streamline knowledge + extraction and retrieval. + {{< comment >}}TODO: Not available in prerelease version + - **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. + {{< /comment >}} + - **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. + - **MLflow integration**: Use the popular MLflow for machine learning + practitioners as part of the ArangoDB Platform. +- **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. +{{< comment >}}TODO: Mostly unrelated to Platform, vector index in core, +- **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. +{{< /comment >}} + + + +## Additional features of the ArangoDB Platform + + + + +## 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/data-science/_index.md b/site/content/3.13/data-science/_index.md index 55d9602ec5..75071cacff 100644 --- a/site/content/3.13/data-science/_index.md +++ b/site/content/3.13/data-science/_index.md @@ -1,34 +1,94 @@ --- -title: Data Science and GenAI -menuTitle: Data Science & GenAI +title: Generative Artificial Intelligence (GenAI) and Data Science +menuTitle: GenAI & Data Science weight: 115 description: >- - ArangoDB lets you apply analytics and machine learning to graph data at scale + ArangoDB's set of tools and technologies enables analytics, machine learning, + and GenAI applications powered by graph data aliases: - data-science/overview --- + +{{< tag "ArangoDB Platform" >}} + +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 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. + + + +## GenAI Suite + +The GenAI Suite is comprised of two major components: + +- [**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. + +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: + +- **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 + 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 + +This section classifies the complexity of the queries you can answer with +ArangoDB and gives you an overview of the respective feature. -ArangoDB, as the foundation for GraphML, comes with the following key features: +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. -- **Scalable**: designed to support true scalability with high performance for +### 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 @@ -71,63 +131,22 @@ GraphML can answer questions like: For ArangoDB's enterprise-ready, graph-powered machine learning offering, see [ArangoGraphML](graphml/_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. - -{{< 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 >}} +### GraphRAG -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 +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. -![ArangoFlix demo](../../images/data-science-arangoflix.png) +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. -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 [GraphRAG](graphrag/_index.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/graphml/_index.md b/site/content/3.13/data-science/graphml/_index.md index ba8e2d6c46..641ba60bad 100644 --- a/site/content/3.13/data-science/graphml/_index.md +++ b/site/content/3.13/data-science/graphml/_index.md @@ -1,12 +1,15 @@ --- 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: - arangographml --- + +{{< tag "ArangoDB Platform" >}} + Traditional Machine Learning (ML) overlooks the connections and relationships between data points, which is where graph machine learning excels. However, accessibility to GraphML has been limited to sizable enterprises equipped with diff --git a/site/content/3.13/data-science/graphml/quickstart.md b/site/content/3.13/data-science/graphml/quickstart.md index 97b9fabeb3..f06e0fb679 100644 --- a/site/content/3.13/data-science/graphml/quickstart.md +++ b/site/content/3.13/data-science/graphml/quickstart.md @@ -9,6 +9,8 @@ aliases: - ../arangographml/deploy --- +{{< tag "ArangoDB Platform" >}} + ## Web interface versus Jupyter Notebooks The ArangoDB Platform provides enterprise-ready Graph Machine Learning in two options, diff --git a/site/content/3.13/data-science/graphml/ui.md b/site/content/3.13/data-science/graphml/ui.md index 45ef75dd6a..602f78e882 100644 --- a/site/content/3.13/data-science/graphml/ui.md +++ b/site/content/3.13/data-science/graphml/ui.md @@ -241,4 +241,4 @@ the Web Interface or export them for downstream use. - **Edge Attributes**: The current version of GraphML does not support the use of edge attributes as features. - **Dangling Edges**: Edges that point to non-existent vertices ("dangling edges") are not caught during the featurization analysis. They may cause errors later, during the Training phase. -- **Memory Usage**: Both featurization and training can be memory-intensive. Out-of-memory errors can occur on large graphs with insufficient system resources. \ No newline at end of file +- **Memory Usage**: Both featurization and training can be memory-intensive. Out-of-memory errors can occur on large graphs with insufficient system resources. diff --git a/site/content/3.13/data-science/graphrag/_index.md b/site/content/3.13/data-science/graphrag/_index.md new file mode 100644 index 0000000000..0ab4bfcab5 --- /dev/null +++ b/site/content/3.13/data-science/graphrag/_index.md @@ -0,0 +1,163 @@ +--- +title: GraphRAG +menuTitle: GraphRAG +weight: 10 +description: >- + ArangoDB's GraphRAG solution combines graph-based retrieval augmented generation + with Large Language Models (LLMs) for turbocharged GenAI solutions +aliases: + llm-knowledge-graphs +--- + +{{< tag "ArangoDB Platform" >}} + +## 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 +constantly expanding and complex datasets. + +LLMs, exemplified by OpenAI's ChatGPT, represent a class of powerful language +transformers. These models leverage advanced neural networks to exhibit a +remarkable proficiency in understanding, generating, and participating in +contextually-aware conversations. + +On the other hand, knowledge graphs contain carefully structured data and are +designed to capture intricate relationships among discrete and seemingly +unrelated information. With knowledge graphs, you can explore contextual +insights and execute structured queries that reveal hidden connections within +complex datasets. + +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 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. + +## 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. + +Key aspects of knowledge graphs: +- **Domain specific knowledge**: You can tailor knowledge graphs to specific + domains and industries. +- **Structured information**: Makes it easy to query, analyze, and extract + meaningful insights from your data. +- **Accessibility**: You can build a Semantic Web knowledge graph or using + custom data. + +LLMs can help distill knowledge graphs from natural language by performing +the following tasks: +- Entity discovery +- Relation extraction +- Coreference resolution +- 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 (private or public) +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 (private or public)** 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) + +### 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 + +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. + +**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. + +**Example query:** + +Local retrieval can answer questions like _**What is the relationship between entity X and entity Y**_? + +This query focuses only on the subgraph involving entities X and Y, extracting detailed relationships and context. + +### Private LLMs + +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](./services/triton-inference-server.md). + +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 LLMs + +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. \ No newline at end of file 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..38393bc8aa --- /dev/null +++ b/site/content/3.13/data-science/graphrag/services/_index.md @@ -0,0 +1,6 @@ +--- +title: GraphRAG services +menuTitle: Services +description: '' +--- + 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 new file mode 100644 index 0000000000..fa5a3cf83e --- /dev/null +++ b/site/content/3.13/data-science/graphrag/services/gen-ai.md @@ -0,0 +1,206 @@ +--- +title: GenAI Orchestration Service +menuTitle: GenAI +description: >- + The GenAI orchestrator service installs, manages, and runs AI-based services + in your Kubernetes cluster +weight: 5 +--- + +{{< tag "ArangoDB Platform" >}} + +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 has its own API endpoint for the deployment. + +**Endpoint LLM Host:** +`https://:8529/gen-ai/v1/llmhost` + +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. + +## 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" + } +} +``` +{{< 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 >}} + +## Using Profiles in Creation Request Body + +```json +{ + "env": { + "model_name": "", + "profiles": "gpu,internal" + } +} +``` + +{{< 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. + +## 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 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 + +The example below shows how to install, monitor, and uninstall a RAGLoader service. + +### Step 1: Installing 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: Checking the 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: Uninstalling 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" + } +} +``` + +{{< 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 + +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"}` + +{{< 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, 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 new file mode 100644 index 0000000000..2cb16af117 --- /dev/null +++ b/site/content/3.13/data-science/graphrag/services/mlflow.md @@ -0,0 +1,146 @@ +--- +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 +--- + +{{< tag "ArangoDB Platform" >}} + +## Overview + +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/index.html) +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 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. + +## Quickstart + +The ArangoDB MLflow service is **started by default**. + +It is 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**. + +{{< 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: + +```bash +curl -X POST https://:8529/_open/auth \ + -d '{"username": "your-username", "password": "your-password"}' +``` + +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 + +First, install the MLflow client: + +```bash +pip install mlflow +``` +There are two approaches for programmatic access to your ArangoDB MLflow service: +- Configuration in Python +- Using environment variables + +### Configuration in Python + +```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") +``` + +### Using 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 Reference](https://mlflow.org/docs/latest/api_reference/rest-api.html). diff --git a/site/content/3.13/data-science/graphrag/services/natural-language-to-aql.md b/site/content/3.13/data-science/graphrag/services/natural-language-to-aql.md new file mode 100644 index 0000000000..981d57f468 --- /dev/null +++ b/site/content/3.13/data-science/graphrag/services/natural-language-to-aql.md @@ -0,0 +1,243 @@ +--- +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 +draft: true +--- +## Overview + +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 +- 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 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 new file mode 100644 index 0000000000..a63a0d3ebd --- /dev/null +++ b/site/content/3.13/data-science/graphrag/services/rag-loader.md @@ -0,0 +1,283 @@ +--- +title: RagLoader Service +menuTitle: RagLoader +description: >- + The RagLoader service helps you transform your text document into a knowledge graph, + making it easier to analyze and understand complex information +weight: 10 +--- + +{{< tag "ArangoDB Platform" >}} + +## Overview + +The RagLoader service lets you turn text files into a knowledge graph. +It supports the following text formats with UTF-8 encoding: +- `.txt` (Plain text) +- `.md` (Markdown) + +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 the RagRetriever service. + +## What ArangoDB Collections look like after import + +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. +- **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 (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. + +### 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 (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. + +### 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 + +## Deployment options + +You can choose between two deployment options based on your needs. + +### Private LLM + +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 + +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. + + +## Installation and configuration + +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. + +### Using Triton Inference Server (Private LLM) + +The first step is to install the LLM Host service with the LLM and +embedding models of your choice. The setup will the use the +Triton Inference Server and MLflow at the backend. +For more details, please refer to the [Triton Inference Server](./triton-inference-server.md) +and [Mlflow](./mlflow.md) documentation. + +Once the `llmhost` service is up-and-running, then you can start the RAGloader +service using the below configuration: + +```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" + }, +} +``` + +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 `llmhost` service is running. +- `triton_model`: Name of the LLM model to use for text processing. + +### Using OpenAI (Public LLM) + +```json +{ + "env": { + "openai_api_key": "your_openai_api_key", + "username": "your_username", + "db_name": "your_database_name", + "api_provider": "openai" + }, +} +``` + +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 + +{{< 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. + +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 + }, + } +``` + +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`) + +{{< info >}} +When using OpenRouter, the service defaults to `mistral-nemo` for generation +(via OpenRouter) and `text-embedding-3-small` for embeddings (via OpenAI). +{{< /info >}} + +## Building Knowledge Graphs + +Once the service is installed successfully, you can follow these steps +to send an input file to the RAGloader 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. \ No newline at end of file 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 new file mode 100644 index 0000000000..b835831230 --- /dev/null +++ b/site/content/3.13/data-science/graphrag/services/rag-retriever.md @@ -0,0 +1,236 @@ +--- +title: RagRetriever Service +menuTitle: RagRetriever +description: >- + RagRetriever is a powerful service that enables intelligent search and + retrieval from knowledge graphs created by the RAGLoader +weight: 15 +--- + +{{< tag "ArangoDB Platform" >}} + +## 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. + +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 + +## Search methods + +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 + +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. + +- **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**: +- "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 is ideal for detailed queries about particular concepts, +entities, or relationships. + +- **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. + +**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]?" + +## 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). + +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) + +The first step is to install the LLM Host service with the LLM and +embedding models of your choice. The setup will the use the +Triton Inference Server and MLflow at the backend. +For more details, please refer to the [Triton Inference Server](./triton-inference-server.md) +and [Mlflow](./mlflow.md) documentation. + +Once the `llmhost` service is up-and-running, then you can start the RAGloader +service using the below configuration: + +```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" + }, +} +``` + +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 `llmhost` service is running. +- `triton_model`: Name of the LLM model to use for text processing. + +### Using OpenAI (Public LLM) + +```json +{ + "env": { + "openai_api_key": "your_openai_api_key", + "username": "your_username", + "db_name": "your_database_name", + "api_provider": "openai" + }, +} +``` + +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. + +{{< 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. + +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 + }, + } +``` + +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`). + +{{< 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 + +After the RagRetriever service is installed successfully, you can interact with +it using the following HTTP endpoints, based on the selected search method. + +{{< tabs "executing-queries" >}} + +{{< tab "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 + }' +``` +{{< /tab >}} + +{{< tab "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 + }' +``` +{{< /tab >}} + +{{< /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 + +You can also monitor the service health: + +```bash +GET /v1/health +``` + +## Best Practices + +- **Choose the right search method**: + - Use global search for broad, thematic queries. + - Use local search for specific entity or relationship 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 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..aed102ca8d --- /dev/null +++ b/site/content/3.13/data-science/graphrag/services/triton-inference-server.md @@ -0,0 +1,190 @@ +--- +title: Triton LLM Host +menuTitle: Triton LLM Host +description: >- + Enable your GraphRAG pipeline to use private LLMs via Triton Inference Server +weight: 30 +--- + +{{< tag "ArangoDB Platform" >}} + +The **Triton LLM Host** service provides scalable deployment of Large Language +Models (LLMs) using the NVIDIA Triton Inference Server. It efficiently serves +machine learning models with support for HTTP and gRPC APIs, customizable routing, +and seamless Kubernetes integration. + +## Workflow + +The Triton LLM Host enables your GraphRAG pipeline to use privately hosted +LLMs directly from the ArangoDB Platform environment. The process involves the +following steps: + +1. Install the Triton LLM Host service. +2. Register your LLM model to MLflow by uploading the required files. +3. Configure the [RagLoader](rag-loader.md#using-triton-inference-server-private-llm) service to use your LLM model. +4. Configure the [RagRetriever](rag-retriever.md#using-triton-inference-server-private-llm) service to use your LLM model. + +{{< tip >}} +Check out the dedicated [ArangoDB MLflow](mlflow.md) documentation page to learn +more about the service and how to interact with it. +{{< /tip >}} + +## Deployment + +The Triton LLM Host service is deployed as a **Kubernetes application** using Helm charts in +the ArangoDB Platform ecosystem. It integrates with the: +- MLFlow model registry for model management. +- Storage sidecar for artifact storage. + +## Installation via GenAI Service API + +To install the Triton LLM Host service, send an API request to the +**GenAI service** using the following parameters: + +### Required parameters + +```json +{ + "models": "model_name", +} +``` +You can also specify multiple models: +- Without versions: `"model_name_1, model_name_2"` +- With versions: `"model_name_1@version1, model_name_2@version2"` +- Mixed: `"model_name_1, model_name_2@version4"` + +### 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 + +All models **must use the Python backend** to ensure compatibility with the +Triton service. Each model requires the following two files: + +1. **`model.py`** + Implements the Python backend model. Triton uses this file to load and + execute your model for inference. + ```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`** + This is the Triton model configuration file that defines essential parameters + such as the model name, backend, and input/output tensors. + ``` + name: "your_model_name" + backend: "python" + max_batch_size: 1 + input: [...] + output: [...] + ``` + +## Model management with MLflow + +{{< info >}} +To prepare your Python backend model for the Triton LLM Host, you must first +register it in MLflow. The Triton LLM Host service automatically downloads +and load models from the MLflow registry. +{{< /info >}} + +### How to register a model in MLflow + +Registering a Python backend model in MLflow involves packaging your +`model.py` and `config.pbtxt` files and passing them as an artifact. The Triton +service will look for a directory named after your model (e.g., `my-private-llm-model`) +within the MLflow registry store and expects to find the `model.py` and `config.pbtxt` +files inside it. + +```py +try: + mlflow.set_tracking_uri(MLFLOW_SERVICE_URI) + with mlflow.start_run() as run: + run_id = run.info.run_id + model_uri = f"runs:/{run_id}/model" + mlflow.register_model(model_uri=model_uri, name=model_name) + # Log the entire model directory as an artifact, preserving the Triton structure + mlflow.log_artifact(local_path=str(local_model_dir)) +``` + +## 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 | + + +{{< info >}} +The Triton Inference Server is not intended to be used in a standalone mode. +Instead, other services consume these endpoints to send inference +requests for example. Refer to the specific service with which you are using +Triton Inference Server for more details. +{{< /info >}} + +- **Internal access (within ArangoDB Platform)**: + `https://{SERVICE_ID}.{KUBERNETES_NAMESPACE}.svc:8000` + - `KUBERNETES_NAMESPACE` is available as an environment variable. + - `SERVICE_ID` is returned by the GenAI service API. + + **Example**: + To check server health: + `GET https://{SERVICE_ID}.{KUBERNETES_NAMESPACE}.svc:8000/v2/health/ready` + +- **External access (outside ArangoDB Platform)**: + `https://{BASE_URL}:8529/llm/{SERVICE_POSTFIX}/` + - `BASE_URL`: Your ArangoDB Platform base URL. + - `SERVICE_POSTFIX`: Last 5 characters of the service ID. + + **Example**: + To check server health: + `GET https://{BASE_URL}:8529/llm/{SERVICE_POSTFIX}/v2/health/ready` + +{{< info >}} +Only HTTP protocol is supported for external access (outside the ArangoDB +Platform). For gRPC, use internal endpoints. This limitation applies to model +inference, model management, model status, and health check endpoints. +{{< /info >}} + +## Triton Inference Server API + +For complete documentation on available endpoints and their usage, +refer to the [Triton Inference Server HTTP API](https://docs.nvidia.com/deeplearning/triton-inference-server/archives/triton_inference_server_1120/triton-inference-server-guide/docs/http_grpc_api.htm) documentation. \ No newline at end of file diff --git a/site/content/3.13/data-science/graphrag/tutorial-notebook.md b/site/content/3.13/data-science/graphrag/tutorial-notebook.md new file mode 100644 index 0000000000..412d7e7ef3 --- /dev/null +++ b/site/content/3.13/data-science/graphrag/tutorial-notebook.md @@ -0,0 +1,407 @@ +--- +title: GraphRAG Notebook Tutorial +menuTitle: Notebook Tutorial +description: >- + Building a GraphRAG pipeline using ArangoDB's integrated notebook servers +weight: 5 +--- + +{{< tag "ArangoDB Platform" >}} + +## Tutorial overview + +This tutorial guides you through the process of building a +Graph-based Retrieval Augmented Generation (GraphRAG) pipeline using +ArangoDB's integrated Notebook servers. GraphRAG is an advanced framework that +combines the power of knowledge graphs (KGs) and large language models (LLMs) +to provide precise and contextually relevant responses from unstructured text data. + +You will learn how to: +- Prepare your raw text data (PDFs in this case) into a structured format + suitable for Knowledge Graph extraction using Docling. +- Utilize the ArangoDB RagLoader service to automatically extract + entities and relationships from your prepared text and store them as a + Knowledge Graph in ArangoDB. +- Query your newly created Knowledge Graph using the ArangoDB RagRetriever + service for both broad (global) and targeted (local) information retrieval. +- Set up a simple Gradio interface to interact with your GraphRAG pipeline. + +## Prerequisites + +Before you begin, ensure you have the following: +- **ArangoDB deployment:** Access to an ArangoDB deployment where you can + create and manage databases. You need the endpoint, your username, and + write access to your chosen database. +- **Python environment:** A Python 3.x environment with `pip` installed. +- **Jupyter Notebook:** This tutorial is designed to be run in ArangoDB's integrated + Notebook servers. +- **OpenAI API key (optional):** If you plan to use OpenAI's models for LLM + processing, you need an OpenAI API key. Alternatively, you can configure the + services to use other providers like Ollama. + +## Environment setup + +This section covers installing necessary libraries, importing Python modules, +and setting up the network functions for interacting with ArangoDB services. + +### Install required libraries + +First, install all the Python libraries necessary for PDF parsing, Markdown +conversion, and interacting with the ArangoDB GraphRAG services. + +```py +! pip install fitz +! pip install PyMuPDF +! pip install PyPDF2 +! pip install markdownify +! pip install docling==2.26.0 +! pip install gradio +``` + +### Import required Python libraries + +Next, import the specific modules and functions used throughout the tutorial. + +```py +import fitz +import requests +import base64 +import os +import re +from PyPDF2 import PdfReader +from docling.document_converter import DocumentConverter +from markdownify import markdownify as md +from typing import Dict, Optional +from pprint import pprint +import time +``` + +## Step 1: Prepare your document + +{{< warning >}} +GraphRAG currently supports `.txt` and `.md` formats only. You can only import one +file at a time. If your document is in `.pdf` format, you must convert it into a +structured Markdown format using Docling. +{{< /warning >}} + +[Docling](https://docling-project.github.io/docling/) from IBM is an AI-based PDF +parsing tool designed to convert complex PDFs into Markdown. This conversion is +crucial for efficient extraction of entities and relationships in the next stage. + +The following process creates a Markdown file for you (e.g., `AliceInWonderland_docling.md`) +from your PDF. The file is automatically added in the file browser of the Jupyter +notebook interface. + +```py +# --- Configuration for your document and database --- +DB_NAME = "documentation" # Set the name of the ArangoDB database you will use for your knowledge graph. Ensure this database already exists in your ArangoDB Deployment. +FILE_NAME = "AliceInWonderland" # Specify the base name of your input file (e.g., 'AliceInWonderland' for 'AliceInWonderland.pdf'). +PDF_NAME=f"./{FILE_NAME}.pdf" # Update the file path and extension if your input document is not a PDF or has a different name. +# ---------------------------------------------------- + +%%time + +def pdf_to_markdown_docling(pdf_file): + """Converts a PDF file to Markdown using Docling.""" + converter = DocumentConverter() + result = converter.convert(pdf_file) + output_md_file = pdf_file.replace(".pdf", "_docling.md") + with open(output_md_file, "w", encoding="utf-8") as md_file: + md_file.write(result.document.export_to_markdown()) + print(f"Successfully converted {pdf_file} to {output_md_file}") + +try: + pdf_to_markdown_docling(PDF_NAME) +except Exception as e: + print(f"An error occurred during PDF to Markdown conversion: {e}") +``` + +The next step is to encode the content of the Markdown file into Base64, +which is required for the RagLoader service. + +```py +%%time + +def encode_file_content(file_path: str) -> Optional[str]: + """Encodes the file content to Base64.""" + try: + with open(file_path, "rb") as file: + encoded_content = base64.b64encode(file.read()).decode("utf-8") + print(f"Successfully encoded file: {file_path}") + return encoded_content + except FileNotFoundError: + print(f"File not found: {file_path}") + except Exception as e: + print(f"Error reading file {file_path}: {e}") + return None + +file_content = encode_file_content(f"./{FILE_NAME}_docling.md") +``` + +## Step 2: Import your document to generate the Knowledge Graph + +Once your document is prepared, you can start the RagLoader service. This +service takes your processed Markdown content, extracts entities and relationships, +and then stores this structured information as a Knowledge Graph within +your specified ArangoDB database. + +### Start the RagLoader (Importer) service + +Start the RagLoader importer service providing the necessary configuration +parameters. + +```py +%%time + +# Start the GraphRAG Importer service +importer_config = { + "db_name": DB_NAME, + "username": os.environ["USERNAME"], + "api_provider": "openai", # Switch the provider if needed (e.g., 'ollama' or 'openai') + "openai_api_key": os.environ["OPENAI_API_KEY"], # Required if api_provider is 'openai' +} + +response = start_service("arangodb-graphrag-importer", importer_config) +pprint(response) + +# Extract the service ID for future reference +importer_service_id = response["serviceInfo"]["serviceId"].split("-")[-1] +print(f"Importer Service ID: {importer_service_id}") +``` + +### Submit your document + +With the importer service running, submit your Base64 encoded Markdown file. +The service will process it in the background to build the Knowledge Graph. + +{{< info >}} +This process can take some time depending on the document's size and complexity. +{{< /info >}} + +```py +%%time + +# Submit the prepared file to generate the Knowledge Graph +importer_payload = { + "file_name": FILE_NAME, + "file_content": file_content, +} + +importerResponse = send_request(f"/graphrag/importer/{importer_service_id}/v1/import", importer_payload, "POST") +pprint(importerResponse) +``` + +### Visualize and interact with the Knowledge Graph + +Once the importer service has processed the document, you can visualize and +interact with the generated Knowledge Graph using the [Graph Visualizer](../../graphs/graph-visualizer.md) +directly from the ArangoDB Platform web interface. + +1. In the ArangoDB Platform web interface, select the database you have previously used. +2. Click **Graphs** in the main navigation. +3. Select the graph named **Knowledge Graph** from the list. +4. The viewport of the Graph Visualizer opens for exploring the graph. +5. In the AQL editor, use the following query to explore communities and + entities: + ```aql + FOR c IN Communities + FILTER c._key == "0" + FOR v,e,p IN 1 INBOUND c GRAPH "KnowledgeGraph" + RETURN p + ``` + +You can also configure the display options: +- Set all **Nodes** collections (e.g., Communities, Entities) to a different color. +- Set the **Communities** label to `title`. +- Set the **Entities** label to `entity_name`. +- For **Edges** (relations), set the label to `type`. + +## Step 3: Query the Knowledge Graph with the RagRetriever service + +To retrieve information from the Knowledge Graph, you need to deploy the +GraphRAG Retriever service. This service interacts with your Knowledge Graph +and uses an LLM to formulate answers to your queries. + +### Startup parameters + +- `api_provider`: Defines to which LLM provider you want to connect (e.g., `ollama`, `openai`). + `ollama` is intended for private LLM usage. +- `openai_api_key`: An API key for usage with ChatGPT. This is only required when + `openai` is selected as the provider. +- `db_name`: The name of the database where your Knowledge Graph was created. +- `username`: The ArangoDB username. This user needs to have write access to the specified database. + +### Start the RagRetriever service + +```py +%%time + +# Start the GraphRAG Retriever service +retriever_config = { + "db_name": DB_NAME, + "username": os.environ["USERNAME"], + "api_provider": "openai", # Change this provider if needed + "openai_api_key": os.environ["OPENAI_API_KEY"], +} + +response = start_service("arangodb-graphrag-retriever", retriever_config) +pprint(response) + +# Extract the service ID for future reference +retriever_service_id = response["serviceInfo"]["serviceId"].split("-")[-1] +print(f"Retriever Service ID: {retriever_service_id}") +``` + +The RagRetriever service is available at the following endpoint, which allows you +to send queries to the Knowledge Graph: +``` +/graphrag/retriever/{service_id}/v1/graphrag-query +``` + +### Query parameters + +The `POST /v1/graphrag-query` API expects the following parameters: + +- `query`: The question you want to ask. +- `query_type`: Can be `1` for a global search (information from the entire KG) + or `2` for a local search (focused on specific subgraphs). +- `level`: Recommended value is `1`. This parameter is relevant for global searches + and defines the hierarchy level of community grouping to start from. +- `provider`: Must be `0` for public LLMs like OpenAI. Use `1` for private LLMs. + +### Example: Global search + +Global retrieval focuses on extracting information from the entire Knowledge Graph. +It is designed to provide a comprehensive overview and answer queries that span +across multiple entities and relationships in the graph. + +For example, you can ask a broad question about the main themes of the document: + +```py +%%time + +# Example for a Global Query +global_query_body = { + "query": "What are the main themes or topics covered in the document?", + "query_type": 1, # 1 = Global search + "level": 1, + "provider": 0, # 0 = OPENAI (based on our setup) + "response_type": "use_query_decomp=True use_llm_planner=True Detailed summary" +} + +print("Executing Global Query...") +retrieverResponse = send_request( + f"/graphrag/retriever/{retriever_service_id}/v1/graphrag-query", + global_query_body, + "POST" +) + +pprint(retrieverResponse["result"]) +``` + +### Example: Local search + +Local retrieval is a focused approach where the query is constrained to +specific subgraphs within the Knowledge Graphs. It is designed for targeted +and precise information extraction. + +For example, you can ask a detailed question about entities within the +Knowledge Graph: + +```py +%%time + +# Example for a Local Query +local_query_body = { + "query": "Who are Alice's relatives?", + "query_type": 2, # 2 = Local search + "level": 1, + "provider": 0, # 0 = OPENAI (based on our setup) + "response_type": "use_query_decomp=True use_llm_planner=True Concise list" +} + +print("Executing Local Query...") +retrieverResponse = send_request( + f"/graphrag/retriever/{retriever_service_id}/v1/graphrag-query", + local_query_body, + "POST" +) + +pprint(retrieverResponse["result"]) +``` + +## Step 4: Create a chat interface via Gradio + +To make querying your Knowledge Graph more interactive, you can use Gradio to +create a simple chat interface. This allows you to submit queries and see real-time +responses from the RagRetriever. + +First, define the functions that handle the queries through the Gradio interface: + +```py +import time + +def global_query(query, messages): + yield from query_graph(query, 1) + +def local_query(query, messages): + yield from query_graph(query, 2) + +def query_graph(query, query_type): + body = { + "query": query, + "query_type": query_type, + "level": 1, + "provider": 0 + } + + retrieverResponse = send_request(f"/graphrag/retriever/{retriever_service_id}/v1/graphrag-query", body, "POST") + result = retrieverResponse["result"] + + response = "" + i = 0 + + while i < len(result): + current_char = result[i] + + # Handle escaped characters + if current_char == '\\': + if i + 1 < len(result): + next_char = result[i + 1] + if next_char == 'n': + response += '\n' + i += 2 + continue + + response += current_char + i += 1 + + yield response + + time.sleep(0.005) +``` +Then, you can launch the global retriever and the local retriever interfaces: + +```py +import gradio as gr + +gr.ChatInterface( + title="ArangoDB GraphRAG Global Retriever", + fn=global_query, + chatbot=gr.Chatbot(height=1000, type="messages"), + type="messages", + theme='JohnSmith9982/small_and_pretty' +).launch(share=True) +``` + +```py +import gradio as gr + +gr.ChatInterface( + title="ArangoDB GraphRAG Local Retriever", + fn=local_query, + chatbot=gr.Chatbot(height=1000, type="messages"), + type="messages", + theme='JohnSmith9982/small_and_pretty' +).launch(share=True) +``` \ No newline at end of file diff --git a/site/content/3.13/data-science/adapters/_index.md b/site/content/3.13/data-science/integrations/_index.md similarity index 87% rename from site/content/3.13/data-science/adapters/_index.md rename to site/content/3.13/data-science/integrations/_index.md index 0aa3efea24..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 -weight: 140 +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). diff --git a/site/content/3.13/data-science/llm-knowledge-graphs.md b/site/content/3.13/data-science/llm-knowledge-graphs.md deleted file mode 100644 index aa5c11bc84..0000000000 --- a/site/content/3.13/data-science/llm-knowledge-graphs.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Large Language Models (LLMs) and Knowledge Graphs -menuTitle: Large Language Models and Knowledge Graphs -weight: 133 -description: >- - Integrate large language models (LLMs) with knowledge graphs using ArangoDB ---- -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 -constantly expanding and complex datasets. - -LLMs, exemplified by OpenAI's ChatGPT, represent a class of powerful language -transformers. These models leverage advanced neural networks to exhibit a -remarkable proficiency in understanding, generating, and participating in -contextually-aware conversations. - -On the other hand, knowledge graphs contain carefully structured data and are -designed to capture intricate relationships among discrete and seemingly -unrelated information. With knowledge graphs, you can explore contextual -insights and execute structured queries that reveal hidden connections within -complex datasets. - -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 - -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. - -Key aspects of knowledge graphs: -- **Domain specific knowledge**: You can tailor knowledge graphs to specific - domains and industries. -- **Structured information**: Makes it easy to query, analyze, and extract - meaningful insights from your data. -- **Accessibility**: You can build a Semantic Web knowledge graph or using - custom data. - -LLMs can help distill knowledge graphs from natural language by performing -the following tasks: -- Entity discovery -- Relation extraction -- Coreference resolution -- End-to-end knowledge graph construction -- (Text) Embeddings - -![ArangoDB Knowledge Graphs and LLMs](../../images/ArangoDB-knowledge-graphs-meets-llms.png) - -## 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/integrations/providers/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). \ No newline at end of file diff --git a/site/content/3.13/data-science/notebook-servers.md b/site/content/3.13/data-science/notebook-servers.md index 553f77d081..f93dfb0892 100644 --- a/site/content/3.13/data-science/notebook-servers.md +++ b/site/content/3.13/data-science/notebook-servers.md @@ -19,15 +19,13 @@ infrastructure, and can immediately start using the GraphML and GenAI functionalities. The notebooks are primarily focused on the following solutions: -- **GraphRAG**: A complete solution for extracting entities +- [GraphRAG](graphrag/_index.md): 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**: Apply machine learning to graphs for link prediction, +- [GraphML](graphml/_index.md): Apply machine learning to graphs for link prediction, classification, and similar tasks. -- **Integrations** : Use ArangoDB together with cuGraph, NetworkX, and other - data science tools. - - +- [Integrations](integrations/_index.md): Use ArangoDB together with cuGraph, + NetworkX, and other data science tools. The ArangoDB Notebooks include the following: - Automatically connect to ArangoDB databases and GenAI platform services @@ -44,9 +42,11 @@ The ArangoDB Notebooks include the following: 3. After your notebook service has been deployed, you can click the ID to start interacting with the Jupyter interface. -{{< tip >}} -To get a better understanding of how to interact with ArangoDB using notebooks, -open the `GettingStarted.ipynb` notebook from the file browser to learn the basics. -{{< /tip >}} +## Examples - +- To get a better understanding of how to interact with ArangoDB using notebooks, + open the `GettingStarted.ipynb` notebook from the file browser to learn the basics. +- To get started with GraphRAG using ArangoDB's integrated notebook servers, see + the [GraphRAG Notebook Tutorial](graphrag/tutorial-notebook.md). +- To get started with GraphML using ArangoDB's integrated notebook servers, see + the [GraphML Notebooks and API](graphml/notebooks-api.md) documentation. diff --git a/site/content/3.13/deploy/_index.md b/site/content/3.13/deploy/_index.md index 7ad9165a5b..e0d36ebcd0 100644 --- a/site/content/3.13/deploy/_index.md +++ b/site/content/3.13/deploy/_index.md @@ -43,6 +43,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. diff --git a/site/content/3.13/graphs/graph-visualizer.md b/site/content/3.13/graphs/graph-visualizer.md index e1a5bc8a88..5d84b8e292 100644 --- a/site/content/3.13/graphs/graph-visualizer.md +++ b/site/content/3.13/graphs/graph-visualizer.md @@ -5,6 +5,9 @@ weight: 102 description: >- Visually explore and interact with your ArangoDB graphs through an intuitive interface --- + +{{< tag "ArangoDB Platform" >}} + The **Graph Visualizer** is a browser-based tool integrated into the web interface of the ArangoDB Platform. It lets you explore the connections of your named graphs to visually understand the structure as well as to inspect and edit the attributes