SEAGIT DOCS
    RAG Stacks

    RAG Stacks

    Reference for SeaGit’s RAG Stack template: what it deploys, how documents are kept in sync, how models are governed, and how the API and web UI are secured. For a walkthrough, start with Deploy a RAG Stack in Minutes.

    Architecture

    A RAG stack is a group of four SeaGit applications deployed together into a cluster in your AWS account and managed as one unit from the Stack tab:

    • vectordb — Qdrant with its index on an encrypted EBS volume.
    • rag-api — embeds questions with Amazon Titan Text Embeddings v2, retrieves the top-k passages from Qdrant and asks an Amazon Bedrock chat model to answer from them, with citations.
    • rag-web-ui (optional) — chat, model picker and drag-and-drop upload.
    • rag-sync — one import job, CronJob and/or event consumer per data source and for uploads.

    Each component gets its own IAM role with only the permissions it needs: read-only access to the folders you chose, write access to the uploads folder, and bedrock:InvokeModel on exactly the approved chat models plus the embedding model.

    With multi-cluster ingestion, every started cluster in the environment runs a complete stack and builds its own index from the same sources, so each region can answer on its own.

    Documents and sync

    Data sources

    A data source is an S3 bucket (optionally one folder and a list of file types) that the stack reads. Each source gets its own sync job. You choose whether to import existing files now, how to keep it in sync, and whether files deleted from the source are removed from the index.

    Uploads

    Uploads are files added through the web UI or POST /v1/ingest. Two separate choices control them:

    • Where uploaded files are kept
      • A new S3 bucket for this stack — created and owned by the stack; optionally deleted with it.
      • Your existing S3 bucket — give the bucket and a folder (for example docs/in/). SeaGit only adds its own access rules for that folder; only that folder is read and synced. Turn on Import existing files now to index what is already there at deploy time.
    • Keep uploads in sync — one of the modes below. Choosing Off turns uploads off: the web UI hides the upload box and /v1/ingest answers 403.

    Sync modes

    ModeWhen a file becomes searchableWhat runs in the cluster
    On change (S3 events)A new or changed file is indexed within seconds; a deleted file can be removed from the index.An event consumer in the cluster, fed by S3 → EventBridge (a direct S3 notification for the stack’s own bucket).
    On a scheduleFiles are picked up on each run of the cron schedule you set (hourly by default). Overlapping runs are skipped.A Kubernetes CronJob that compares the folder with the index.
    On change + safety sweepSeconds for normal changes, and the scheduled sweep catches anything an event missed. The default.Both of the above.
    Off / Don’t syncFor uploads: the upload box and upload API are turned off. For a data source: only the import at deploy time.Nothing.

    Right after a stack is created, S3 can take a few minutes to start sending events for a bucket. A file uploaded in that window is picked up by the next safety sweep — another reason On change + safety sweep is the default.

    Buckets in another AWS account

    A bucket can live in any AWS account your organization has connected as a provider. Under Bucket access:

    • Automatic — SeaGit finds the bucket’s account among your organization’s AWS providers. If the bucket is in a different account from the cluster, enter its AWS account ID so SeaGit knows where to look.
    • Pick credentials — choose the provider that owns the bucket.
    • Use an existing IAM role — launch the provided CloudFormation link in the bucket’s account and paste the role ARN; SeaGit never needs credentials for that account.

    SeaGit creates a role in the bucket’s account scoped to your folder, and for event sync an EventBridge rule for that bucket and folder only. Deleting the stack removes both and leaves your bucket and files untouched. If the account ID you enter doesn’t own the bucket, the components that use it (rag-api and rag-sync) fail to deploy and nothing is created in the bucket’s account; delete the stack and deploy it again with the right account.

    Approved models

    Which Bedrock chat models a stack may use is decided at three levels, each a subset of the one above:

    1. Account (account settings → Approved models) — all catalog models, or a chosen list, plus the default for organizations without their own list.
    2. Organization (Approved models in the organization sidebar) — narrows the account’s list. “Nothing approved” means no model is available.
    3. Stack — the chat models picked in the deploy wizard, and a default.

    The rules are enforced, not advisory: /v1/models lists only the stack’s models, a request naming any other model is refused with 400, and the stack’s IAM role can only invoke those models. When an admin removes a model from the account or an organization, organization lists are pruned, the Stack tab warns about stacks still using it, and the next redeploy from the Stack tab drops the model and its permission.

    Anthropic, Meta and Mistral models also need model access enabled for the AWS account in the Amazon Bedrock console. If it is missing, the web UI says which model isn’t enabled instead of failing silently.

    Access keys

    • API key — for applications. Send it as Authorization: Bearer <key>.
    • Web UI access key — for people. The web UI exchanges it for a short-lived session; the key itself is never embedded in the page. After 10 wrong attempts, sign-in is rate-limited.

    Both keys are shown once, when the stack is created. Rotate the web UI key from the Stack tab: the new key is shown once, and existing sessions stop working as soon as the change rolls out (usually under a minute).

    API

    MethodPathPurpose
    POST/v1/queryAsk a question; returns the answer, the model used and numbered citations.
    POST/v1/chat/completionsOpenAI-compatible chat. `model` must be "rag" or one of the stack’s approved models. No streaming yet.
    GET/v1/modelsThe chat models this stack allows, and the default.
    POST/v1/ingestUpload a file (multipart `file`). Returns `stored`; it becomes searchable per the uploads sync setting.
    GET/v1/uploadsWhether uploads are on, the sync mode and the schedule.
    POST/v1/ui/sessionExchange the web UI access key for a session token (used by the web UI).

    /v1/query and /v1/chat/completions accept an optional model; without it the stack’s default model answers. Questions are limited to 8,000 characters.

    curl -s https://<api-host>/v1/query \
  -H "Authorization: Bearer $RAG_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"question": "Summarise the travel policy", "model": "bedrock:us.amazon.nova-pro-v1:0"}'

    Troubleshooting

    • A new upload isn’t found — check GET /v1/uploads. With On a schedule the file is indexed on the next run; right after stack creation an event may be missed until the next sweep.
    • “model … is not approved for this assistant” — the model isn’t in the stack’s list; see Approved models.
    • “… isn’t enabled in Bedrock” — enable model access for that model in the AWS account.
    • “uploads are turned off for this stack” — uploads sync is set to Off.
    • A component stays pending — the cluster may be out of capacity; see Troubleshooting.