mirror of
https://github.com/documenso/documenso.git
synced 2026-06-22 04:12:06 +10:00
Lucas Smith
107 lines
3.7 KiB
Plaintext
107 lines
3.7 KiB
Plaintext
---
|
|
title: AI Recipient & Field Detection (Self-hosting)
|
|
description: Configure Google Vertex AI so Documenso can detect recipients and fields automatically.
|
|
---
|
|
|
|
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
|
|
import { Callout } from 'fumadocs-ui/components/callout';
|
|
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
|
|
|
## Overview
|
|
|
|
This guide covers how to enable the AI recipient and field detection features when you self-host Documenso.
|
|
|
|
## What This Enables
|
|
|
|
- Detect recipients from uploaded PDFs (roles, names, emails when present).
|
|
- Detect and place fields (signature, initials, name, email, date, text, number, radio, checkbox) onto draft envelopes.
|
|
- Built-in rate limits (3 requests per minute per IP) to prevent abuse.
|
|
|
|
## Prerequisites
|
|
|
|
- A Google Cloud project with the **Vertex AI API** enabled and billing active.
|
|
- A **Vertex AI Express API key** with access to Gemini models (create via the [Vertex AI Express flow](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview) and manage keys in [API keys](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys)).
|
|
- Documenso version that includes the AI detection feature and the corresponding database migration.
|
|
|
|
## Configure Environment Variables
|
|
|
|
Add these variables to your deployment `.env` (or secret manager):
|
|
|
|
```
|
|
GOOGLE_VERTEX_PROJECT_ID="<your-gcp-project-id>"
|
|
GOOGLE_VERTEX_API_KEY="<your-vertex-api-key>"
|
|
# Optional, defaults to "global"
|
|
GOOGLE_VERTEX_LOCATION="global"
|
|
```
|
|
|
|
<Callout type="info">
|
|
Use a region close to your users if you need data residency considerations (e.g. `europe-west1`).
|
|
If you omit the location, Documenso uses `global`. Not all models are available in every region;
|
|
if a model is unavailable, switch to a supported region.
|
|
</Callout>
|
|
|
|
## Deploy with the Published Container
|
|
|
|
- Use the official Documenso image (DockerHub or GHCR) and supply the Vertex env vars above.
|
|
- Ensure migrations run on startup (the container runs `prisma migrate deploy` in production mode).
|
|
- Restart the container after adding or changing Vertex env vars.
|
|
|
|
## Enable the Feature in Documenso
|
|
|
|
Once the service is running with the Vertex env vars:
|
|
|
|
{/* prettier-ignore */}
|
|
<Steps>
|
|
<Step>
|
|
### Organisation settings
|
|
|
|
Go to **Settings** → **Document Preferences** → **AI Features** and set to **Enabled**.
|
|
|
|
Teams that inherit organisation defaults will get this automatically.
|
|
|
|
</Step>
|
|
<Step>
|
|
### Team settings
|
|
|
|
If a team overrides organisation defaults:
|
|
|
|
- Go to **Team Settings** → **Document Preferences** → **AI Features**
|
|
- Choose **Enabled**, or **Inherit** to follow the organisation
|
|
|
|
</Step>
|
|
<Step>
|
|
### Verify in the editor
|
|
|
|
Open a draft envelope and check:
|
|
|
|
- **Recipients**: sparkle button for AI detection is visible
|
|
- **Fields**: **Detect with AI** is available
|
|
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Troubleshooting
|
|
|
|
<Accordions type="multiple">
|
|
<Accordion title="Too many requests">
|
|
Wait a minute or two and retry (rate limit is 3/min per IP).
|
|
</Accordion>
|
|
<Accordion title="AI options hidden">
|
|
Ensure the env vars are set, the server was restarted after setting them, and
|
|
`aiFeaturesEnabled` is enabled at organisation/team level.
|
|
</Accordion>
|
|
<Accordion title="Detection fails immediately">
|
|
Confirm the Vertex API key is valid and the project has Vertex AI enabled. Check server logs for
|
|
status codes from Vertex.
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
If issues persist, recheck env vars, restart the service, and confirm the Prisma migration was applied.
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- [AI Detection (User Guide)](/docs/users/documents/advanced/ai-detection) - How to use AI detection features
|
|
- [Environment Variables](/docs/self-hosting/configuration/environment) - All configuration options
|