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.

Applying the changes to all versions no longer needed. The AI suite folder has been removed from the ArangoDB versioned folders.

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/ai-suite/reference/importer.md

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

site/content/ai-suite/reference/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/ai-suite/reference/importer.md

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

diegomendez40

Added a couple of comments.

site/content/ai-suite/reference/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.

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.

site/content/ai-suite/reference/gen-ai.md

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

site/content/ai-suite/reference/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/ai-suite/reference/importer.md


 {{< 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.)
+### 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.

site/content/ai-suite/reference/retriever.md

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/ai-suite/reference/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.

Co-authored-by: Anthony Mahanna <43019056+aMahanna@users.noreply.github.com>

…tion rules

…oject creation; move and extend Projects

…eries

diegomendez40

Thanks for your work, @nerpaula.

This version is far better -- far more accurate. Still, I managed to find a couple of possible enhancements. Thanks for considering them before merging.

diegomendez40 · 2025-11-06T20:04:42Z

site/content/ai-suite/reference/gen-ai.md

+      "chat_api_provider": "<your-api-provider>",
+      "chat_api_key": "<your-llm-provider-api-key>",
+      "chat_model": "<model-name>"


I don't think this example is right.

You'd also need an embedding_api_provider:

https://github.com/arangoml/graphrag_importer/blob/main/charts/arangodb-graphrag-importer/templates/deployment.yaml#L1-L5

And then, due to the providers that we actually support, since you're already using a chat_api_key you're using an OpenAI-compatible API, which means you'd also need an embedding_api_key.

Just to be sure I'd use all these args:

- "db_name" - "chat_api_provider" - "embedding_api_provider" - "chat_model" - "embedding_model" - "chat_api_url" - "embedding_api_url" - "embedding_dim"

👀 @aMahanna @anyxling

Quick question about "embedding_dim". Should we add this to all examples, currently missing. Optional, I suppose? How can one decide the embedding dimension?

diegomendez40 · 2025-11-06T20:09:45Z

site/content/ai-suite/reference/retriever.md

-graph and get contextually relevant responses.
+The Retriever service provides intelligent search and retrieval from knowledge graphs,
+with multiple search methods optimized for different query types. The service supports 
+both private (Triton Inference Server) and public (any OpenAI-compatible API) LLM 


A corporate LLM isn't necessarily public. We've done projects with customers where we have been using their private LLMs via an OpenAI-compatible API.

Thus, the distinction private-Triton vs. public-OpenAI-compatible is false. OpenAI-compatible can be private.

diegomendez40 · 2025-11-06T20:18:18Z

site/content/ai-suite/reference/retriever.md


 The Retriever service can be configured to use either the Triton Inference Server
-(for private LLM deployments) or OpenAI/OpenRouter (for public LLM deployments).
+(for private LLM deployments) or any OpenAI-compatible API (for public LLM deployments), 


false private Triton/public OpenAI-compatible dichotomy

diegomendez40 · 2025-11-06T20:21:22Z

site/content/ai-suite/reference/retriever.md

-  - `1`: Global search.
-  - `2`: Local search.
+  - `GLOBAL` or `1`: Global Search (default if not specified).
+  - `LOCAL` or `2`: Deep Search when used with LLM planner, or standard Local Search without the planner.


Suggested change

- `LOCAL` or `2`: Deep Search when used with LLM planner, or standard Local Search without the planner.

- `LOCAL` or `2`: Deep Search when used with LLM planner (default), or standard Local Search when llm_planner is explicitly set to false.

diegomendez40 · 2025-11-06T20:21:48Z

site/content/ai-suite/reference/retriever.md

+  - `UNIFIED` or `3`: Instant Search.
+
+- `use_llm_planner`: Whether to use LLM planner for intelligent query orchestration (optional)
+  - When enabled, orchestrates retrieval using both local and global strategies (powers Deep Search)


Suggested change

- When enabled, orchestrates retrieval using both local and global strategies (powers Deep Search)

- When enabled (default), orchestrates retrieval using both local and global strategies (powers Deep Search)

bluepal-keerthi-datla · 2025-11-07T06:10:09Z

site/content/ai-suite/reference/importer.md

-By default, for OpenAI API, the service is using
-`gpt-4o-mini` and `text-embedding-3-small` models as LLM and
-embedding model respectively.
+When using the official OpenAI API, the service defaults to `gpt-4o-mini` and 


Docs say default models are gpt-4o-mini, but code uses gpt-4o. Please update docs to match actual behavior.

Refs: server.py:197, graph_builder.py:183

bluepal-keerthi-datla · 2025-11-07T06:13:05Z

site/content/ai-suite/reference/retriever.md

-By default, for OpenAI API, the service is using
-`gpt-4o-mini` and `text-embedding-3-small` models as LLM and
-embedding model respectively.
+When using the official OpenAI API, the service defaults to `gpt-4o-mini` and 


Same as mentioned above docs has the default model gpt-4o-mini, but the code uses gpt-4o. update the docs to reflect the actual behavior.

Refs: server.py:197, graph_builder.py:183

bluepal-keerthi-datla · 2025-11-07T06:22:03Z

site/content/ai-suite/reference/importer.md

-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.
+You can mix and match any OpenAI-compatible APIs for chat and embedding. For example, 


Docs currently state that chat and embedding providers can be mixed, but the code blocks this and raises an error:
server.py(149-154)
if args.chat_api_provider != args.embedding_api_provider:
raise ValueError("Chat API provider and embedding API provider must be the same.")

Please update the docs — either remove this section or mark it as a planned feature.
Suggested note:
Mixed provider support is planned. Currently, both chat_api_provider and embedding_api_provider must match (OpenAI or Triton).

@bluepal-keerthi-datla I wanted to illustrate in this example that you can use different OpenAI-compatible services - as in OpenRouter for chat and OpenAI for embeddings by setting both providers to "openai" and differentiating them with different URLs . I see that this can be confusing since both are considered the same provider type. I will change the section title to reflect this and clarify that you cannot mix Triton and OpenAI-compatible APIs.

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 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

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/ai-suite/reference/importer.md Show resolved Hide resolved

bluepal-pavan-kothapalli reviewed Oct 31, 2025

View reviewed changes

site/content/ai-suite/reference/importer.md Outdated Show resolved Hide resolved

bluepal-pavan-kothapalli reviewed Oct 31, 2025

View reviewed changes

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

diegomendez40 requested changes Nov 4, 2025

View reviewed changes

nerpaula and others added 10 commits November 4, 2025 22:05

update startup parameters

a4dd3b5

Apply suggestions from code review

a32d841

Co-authored-by: Anthony Mahanna <43019056+aMahanna@users.noreply.github.com>

apply changes to all versions, fix typo

02adb50

instant and deep search

3504267

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

bec2f30

add missing description for chat_api_url

b33024b

fix typo

e48a6d0

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

81d49fb

…tion rules

remove username from startup parameters

e657d19

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

52176ce

…oject creation; move and extend Projects

Simran-B force-pushed the DOC-790 branch from cbb782f to 52176ce Compare November 4, 2025 21:26

Simran-B changed the base branch from main to DOC-761 November 4, 2025 21:27

Merge branch 'DOC-761' into DOC-790

b764373

nerpaula added 2 commits November 5, 2025 20:50

clarify project requirements; clarify OpenAI-compatible API usage

dcc8be1

restructure and clarify all available search methods and executing qu…

59cdb87

…eries

nerpaula requested a review from diegomendez40 November 6, 2025 12:08

diegomendez40 requested review from bluepal-keerthi-datla and bluepal-pavan-kothapalli November 6, 2025 15:02

diegomendez40 approved these changes Nov 6, 2025

View reviewed changes

bluepal-keerthi-datla reviewed Nov 7, 2025

View reviewed changes

address review comments

037006d

	- `LOCAL` or `2`: Deep Search when used with LLM planner, or standard Local Search without the planner.
	- `LOCAL` or `2`: Deep Search when used with LLM planner (default), or standard Local Search when llm_planner is explicitly set to false.

	- When enabled, orchestrates retrieval using both local and global strategies (powers Deep Search)
	- When enabled (default), orchestrates retrieval using both local and global strategies (powers Deep Search)

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!

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!

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!

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!

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

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

nerpaula commented Oct 17, 2025 •

edited

Loading

bluepal-pavan-kothapalli commented Oct 31, 2025 •

edited

Loading

nerpaula commented Oct 31, 2025 •

edited

Loading

nerpaula Nov 7, 2025 •

edited

Loading

bluepal-keerthi-datla Nov 7, 2025 •

edited

Loading

nerpaula Nov 7, 2025 •

edited

Loading