DOC-790 | Importer & Retriever: Update startup parameters #809

nerpaula · 2025-10-17T11:51:00Z

Description

Importer & Retriever: Update startup parameters., including descriptions and parameters for instant and deep search.

TO DO:

Apply changes to all versions

arangodb-docs-automation · 2025-10-17T11:51:04Z

Deploy Preview Available Via
https://deploy-preview-809--docs-hugo.netlify.app

aMahanna

LGTM! minor comment about including embedding_api_provider

site/content/3.12/data-science/graphrag/services/importer.md

aMahanna · 2025-10-17T19:26:06Z

site/content/3.12/data-science/graphrag/services/importer.md

-        "openrouter_model": "mistralai/mistral-nemo"  // Specify a model here
+        "chat_api_provider": "openai",
+        "embedding_api_provider": "openai",
+        "chat_api_url": "https://openrouter.ai/api/v1",


This is fine - since setting openai as the provider means that we just use the OpenAI() client to interact with the OpenRouter URL, which is OpenAI-compatible

site/content/3.12/data-science/graphrag/services/importer.md

site/content/3.12/data-science/graphrag/services/retriever.md

Co-authored-by: Anthony Mahanna <[email protected]>

site/content/3.12/data-science/graphrag/services/retriever.md

diegomendez40

Added a couple of comments.

site/content/3.12/data-science/graphrag/services/importer.md

site/content/3.12/data-science/graphrag/services/retriever.md

bluepal-pavan-kothapalli · 2025-10-31T13:39:35Z

IMHO: It would be great if we could provide short documentation on how to create a project in genai-service.

Create a New Project

Endpoint: POST /v1/project

Validation: The name must be 1–63 characters long and can only contain letters, numbers, underscores, and hyphens.

Request Body:

json
{
"project_name": "my_project_1",
"project_type": "ML",
"project_description": "My project description"
}
This project can then be referenced in other services, like the importer or retriever, using the genai_project_name field:

json
{
"genai_project_name": "my_project_1"
}

WDYT?
CC @diegomendez40

nerpaula · 2025-10-31T13:45:18Z

IMHO: It would be great if we could provide short documentation on how to create a project in genai-service.

Create a New Project

Endpoint: POST /v1/project

Validation: The name must be 1–63 characters long and can only contain letters, numbers, underscores, and hyphens.

Request Body:

json { "project_name": "my_project_1", "project_type": "ML", "project_description": "My project description" } This project can then be referenced in other services, like the importer or retriever, using the genai_project_name field:

json { "genai_project_name": "my_project_1" }

WDYT? CC @diegomendez40

@bluepal-pavan-kothapalli There is a section on how to create a new project, in importer.md line 33. We should however reference this in the Retriever page as well.

cursor · 2025-10-31T14:53:30Z

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on November 28.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

…tion rules

…oject creation; move and extend Projects

nerpaula · 2025-11-04T16:49:29Z

@diegomendez40 @bluepal-pavan-kothapalli FYI changes from my two latest commits:

remove username from startup parameters
add project_db_name as required parameter when creating a new project
after some careful consideration, I have decided that the Project endpoint deserves a better description and a section of its own in the GenAI Orchestrator service. I have further improved the content and moved it over. The Importer and Retriever have references to the respective section and marked as a prerequisite.

diegomendez40

Thanks for your work, @nerpaula. Unfortunately, I have found a number of possible enhancements and corrections.

While I added most of them to the 3.12 folder, they do also apply to 3.13.

diegomendez40 · 2025-11-04T17:55:52Z

site/content/3.12/data-science/graphrag/services/gen-ai.md

-## Using Profiles in Creation Request Body
+### Creating a project
+
+To create a new GraphRAG project, send a POST request to the project endpoint:


It probably makes sense to mention that only 3 services require a project:

Importer

Retrievers

VirtualGraph (but that's not part of this release as of today, will follow very soon)

https://github.com/arangoml/GenAI-Service/blob/main/gen_ai/naming.py#L26-L29

diegomendez40 · 2025-11-04T18:00:02Z

site/content/3.12/data-science/graphrag/services/importer.md

- `triton_model`: Name of the LLM model to use for text processing.
-
-### Using OpenAI (Public LLM)
+### Using OpenAI for chat and embedding


"openai" doesn't stand for OpenAI, but rather for any OpenAI-compatible API, including essentially any large LLM provider: OpenRouter, Gemini, Anthropic, corporate LLMs, etc.

The URL can point to the relevant non-OpenAI endpoint, even if it is served via an OpenAI-compatible API.

diegomendez40 · 2025-11-04T18:00:54Z

site/content/3.12/data-science/graphrag/services/importer.md

 {{< /info >}}

-### Using OpenRouter (Gemini, Anthropic, etc.)
+### Using OpenRouter for chat and OpenAI for embedding


It's not just OpenRouter. It's literally any OpenAI compatible API.

diegomendez40 · 2025-11-04T18:02:44Z

site/content/3.12/data-science/graphrag/services/retriever.md

+- **Instant search**: Focuses on specific entities and their relationships, ideal
+  for fast queries about particular concepts.
+- **Deep search**: Analyzes the knowledge graph structure to identify themes and patterns,
+  perfect for comprehensive insights and detailed summaries.


Unfortunately, these definitions are incorrect. These are the definitions for global and local. However, I had already provided the relevant definitions for instant vs. deep search, which can be used here.

diegomendez40 · 2025-11-04T18:03:44Z

site/content/3.12/data-science/graphrag/services/retriever.md

+Deep Search is designed for highly detailed, accurate responses that require understanding
+what kind of information is available in different parts of the knowledge graph and
+sequentially retrieving information in an LLM-guided research process. Use whenever
+detail and accuracy are required (e.g. aggregation of highly technical details) and
+very short latency is not (i.e. caching responses for frequently asked questions,
+or use case with agents or research use cases).


diegomendez40 · 2025-11-04T18:07:28Z

site/content/3.12/data-science/graphrag/services/retriever.md

 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).
+- `level`: The community hierarchy level to use for the search (`1` for top-level communities). Defaults to `2` if not provided.


You don't need the 'level' parameter. That's for global queries.

diegomendez40 · 2025-11-04T18:09:38Z

site/content/3.12/data-science/graphrag/services/retriever.md

-  - `1`: Global search.
-  - `2`: Local search.


Global and local queries still exist. They are supported.

The fact that we don't use them on the UI doesn't mean they can't be used by experts.

diegomendez40 · 2025-11-04T18:10:34Z

site/content/3.12/data-science/graphrag/services/retriever.md

+  - `UNIFIED`: Instant search.
+  - `LOCAL`: Deep search.


This isn't exactly right.

Local with no LLM planner is the typical local query.

Local with LLM planner is Deep Search.

diegomendez40 · 2025-11-04T18:12:18Z

site/content/3.13/data-science/graphrag/services/importer.md

 {{< /info >}}

-### Using OpenRouter (Gemini, Anthropic, etc.)
+### Using OpenRouter for chat and OpenAI for embedding


Again, this should mention any OpenAI compatible API, not just OpenRouter

diegomendez40 · 2025-11-04T18:13:21Z

site/content/3.13/data-science/graphrag/services/retriever.md

+- **Instant search**: Focuses on specific entities and their relationships, ideal
+  for fast queries about particular concepts.
+- **Deep search**: Analyzes the knowledge graph structure to identify themes and patterns,
+  perfect for comprehensive insights and detailed summaries.


All changes above (on 3.12) should be replicated for 3.13.

update startup parameters

4b7523c

cla-bot bot added the cla-signed label Oct 17, 2025

nerpaula self-assigned this Oct 17, 2025

This comment was marked as outdated.

Sign in to view

aMahanna reviewed Oct 17, 2025

View reviewed changes

nerpaula and others added 5 commits October 22, 2025 12:36

Apply suggestions from code review

b9cb2f6

Co-authored-by: Anthony Mahanna <[email protected]>

apply changes to all versions, fix typo

f49407b

Merge branch 'main' into DOC-790

44fbf7f

update links

5c6505c

instant and deep search

9f02444

nerpaula commented Oct 24, 2025

View reviewed changes

site/content/3.12/data-science/graphrag/services/retriever.md Outdated Show resolved Hide resolved

nerpaula commented Oct 24, 2025

View reviewed changes

site/content/3.12/data-science/graphrag/services/retriever.md Outdated Show resolved Hide resolved

diegomendez40 reviewed Oct 24, 2025

View reviewed changes

update description of instant and deep search; fix some anchor links

f4abfcb

diegomendez40 requested a review from bluepal-pavan-kothapalli October 31, 2025 12:08

bluepal-pavan-kothapalli reviewed Oct 31, 2025

View reviewed changes

site/content/3.12/data-science/graphrag/services/importer.md Show resolved Hide resolved

bluepal-pavan-kothapalli reviewed Oct 31, 2025

View reviewed changes

site/content/3.12/data-science/graphrag/services/importer.md Show resolved Hide resolved

bluepal-pavan-kothapalli reviewed Oct 31, 2025

View reviewed changes

site/content/3.12/data-science/graphrag/services/retriever.md Show resolved Hide resolved

add missing description for chat_api_url

dd7e054

nerpaula and others added 5 commits October 31, 2025 15:56

fix typo

99c7162

reference project creation in retriever file; add project name valida…

cb48714

…tion rules

Merge branch 'main' into DOC-790

7f1f494

remove username from startup parameters

1258f72

update startup parameters in genai service; add project_db_name in pr…

cbb782f

…oject creation; move and extend Projects

diegomendez40 requested changes Nov 4, 2025

View reviewed changes

DOC-790 | Importer & Retriever: Update startup parameters #809

Are you sure you want to change the base?

DOC-790 | Importer & Retriever: Update startup parameters #809

Conversation

nerpaula commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

arangodb-docs-automation bot commented Oct 17, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

aMahanna left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

diegomendez40 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bluepal-pavan-kothapalli commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nerpaula commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor bot commented Oct 31, 2025

Uh oh!

nerpaula commented Nov 4, 2025

Uh oh!

diegomendez40 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nerpaula commented Oct 17, 2025 •

edited

Loading

bluepal-pavan-kothapalli commented Oct 31, 2025 •

edited

Loading

nerpaula commented Oct 31, 2025 •

edited

Loading