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:
- 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. - Run the installer for the version you already have, as administrator.
- On the components screen, select VTRAG and leave the other components as they are. The installer keeps your existing installation and data.
- 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 invtrag.env.ps1. - The installer said the vtrag database was not set up: VisibleThread uses an external PostgreSQL server. Create the database from
setup\vtrag.sqlas in the Windows deployment guide, then start thevtdocs-vtragservice. - Bedrock access denied: the server's IAM role is missing
bedrock:InvokeModelon the Titan V2 model, orAWS_REGIONis wrong.