How can we help?

Search the knowledge base or browse by topic.

Follow

How to deploy VTRAG for VisibleThread 7 on Windows

VTRAG is the service behind the VisibleThread 7 AI features that search your documents. It turns your documents into embeddings with an embeddings model you provide, stores them in PostgreSQL with pgvector, and answers searches from VisibleThread.

On Windows, VTRAG is an optional component of the VisibleThread installer. This guide adds it to a VisibleThread 7 server and connects it to your embeddings model. For RHEL, see How to deploy VTRAG for VisibleThread 7 on RHEL 8 and RHEL 9.

Before you start

You need:

  • VisibleThread 7 on Windows Server, installed as in How to Deploy VisibleThread 7+ on Windows, or a new server you are about to install.
  • The VisibleThread installer for the version you run.
  • An embeddings model in Azure OpenAI or Amazon Bedrock.
  • Administrator access to the server.

VisibleThread is already configured to reach VTRAG on the same server.

Step 1: Install the VTRAG component

New server: run the installer as in the Windows deployment guide and keep VTRAG selected on the components screen.

VisibleThread already installed without VTRAG:

  1. Stop all the VisibleThread services. In PowerShell as administrator:
    Get-Service vtdocs-* | Stop-Service -Force
    If they are running, the installer cannot replace its files, stops with Could not remove the previous VT Docs vtapi and vtrag files, and rolls back.
  2. Run the installer for the version you already have, as administrator.
  3. On the components screen, select VTRAG and leave the other components as they are. The installer keeps your existing installation and data.
  4. When it finishes, start any VisibleThread service that is still stopped. The installer does not restart vtdocs-vtapi:
    Get-Service vtdocs-* | Start-Service

With the bundled PostgreSQL, the installer creates the vtrag database with the pgvector extension, installs the vtdocs-vtrag service, and starts it.

If VisibleThread uses an external PostgreSQL server, the installer cannot create the database and says so at the end. Create it from setup\vtrag.sql as in the external database section of the Windows deployment guide, then continue with step 2.

Step 2: Choose your embeddings model

Edit C:\Program Files\VisibleThread\vtdocs\incl\vtrag.env.ps1 as administrator. This is a PowerShell file: plain settings start with $, and settings the service reads directly start with $ENV:.

The file ships set up for a local Ollama server as a placeholder. Change $SPRING_PROFILE and add the lines for your provider at the end of the file. Leave the database settings and the Do Not Modify block as they are.

Azure OpenAI

Create an embeddings deployment in your Azure OpenAI resource first, for example text-embedding-3-large. Use the deployment name, which can differ from the model name.

$SPRING_PROFILE = "azure-openai"

## Azure OpenAI ##
$AZURE_OPENAI_API_KEY_ID = "<your-api-key>"
$AZURE_OPENAI_ENDPOINT = "https://<your-resource>.cognitiveservices.azure.com/"
$AZURE_OPENAI_DEPLOYMENT_NAME = "<your-deployment-name>"
$AZURE_OPENAI_CHAT_ENABLED = "false"

## Azure OpenAI - Do Not Modify ##
$ENV:SPRING_AI_AZURE_OPENAI_API_KEY="${AZURE_OPENAI_API_KEY_ID}"
$ENV:SPRING_AI_AZURE_OPENAI_ENDPOINT="${AZURE_OPENAI_ENDPOINT}"
$ENV:SPRING_AI_AZURE_OPENAI_EMBEDDING_OPTIONS_DEPLOYMENT_NAME="${AZURE_OPENAI_DEPLOYMENT_NAME}"
$ENV:SPRING_AI_AZURE_OPENAI_CHAT_ENABLED="${AZURE_OPENAI_CHAT_ENABLED}"
$ENV:SPRING_AI_VECTORSTORE_PGVECTOR_DIMENSIONS = 1024
$ENV:SPRING_AI_AZURE_OPENAI_EMBEDDING_OPTIONS_DIMENSIONS = 1024

text-embedding-3-small and text-embedding-3-large both work at 1024 dimensions. text-embedding-ada-002 does not support the dimensions setting.

Amazon Bedrock

VTRAG uses the Titan Text Embeddings V2 model (amazon.titan-embed-text-v2:0) and signs in with the standard AWS credentials on the server. On EC2 that is the instance's IAM role, and you need no keys in the file.

$SPRING_PROFILE = "bedrock"

## Amazon Bedrock ##
$ENV:AWS_REGION = "<your-region>"

Use a region where Titan Text Embeddings V2 is available. The server's IAM role needs permission to call the model:

{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "arn:aws:bedrock:<your-region>::foundation-model/amazon.titan-embed-text-v2:0"
}

Step 3: Restart and check VTRAG

Restart the vtdocs-vtrag service from Services, or in PowerShell as administrator:

Restart-Service vtdocs-vtrag

Check that it is healthy:

curl.exe -s -o NUL -w "%{http_code}" http://localhost:8010/actuator/health

It should print 200. VTRAG can take a minute to start.

Changing provider later

Edit vtrag.env.ps1 as in step 2, then restart the vtdocs-vtrag service.

Troubleshooting

  • VTRAG will not start or indexing fails: check C:\Program Files\VisibleThread\vtdocs\logs\vtrag.log. A connection or authentication error there usually means a wrong endpoint, key, deployment name or region in vtrag.env.ps1.
  • The installer said the vtrag database was not set up: VisibleThread uses an external PostgreSQL server. Create the database from setup\vtrag.sql as in the Windows deployment guide, then start the vtdocs-vtrag service.
  • Bedrock access denied: the server's IAM role is missing bedrock:InvokeModel on the Titan V2 model, or AWS_REGION is wrong.
Was this article helpful?
0 out of 0 found this helpful

Get Additional Help

Reach out to support@visiblethread.com to create a ticket.