127 lines
6.8 KiB
Markdown
127 lines
6.8 KiB
Markdown
# 15 — Configuration
|
||
|
||
## Where configuration is defined
|
||
|
||
`apps/ai-service/config.py` is the single authority for the Python service:
|
||
every setting is a field on the Pydantic `Settings` class, loaded from the
|
||
environment or from a `.env` file next to the process, with `extra="ignore"`.
|
||
`get_settings()` is `@lru_cache`d, so values are read once per process.
|
||
|
||
There is **no `.env.example` anywhere in the repository**. The only env file is
|
||
`apps/ai-service/.env`, which is gitignored and local; production uses
|
||
`apps/ai-service/.env.prod`, which is also gitignored and lives only on the EC2
|
||
host. A new engineer therefore has no committed template to copy — see
|
||
[27-technical-debt.md](27-technical-debt.md).
|
||
|
||
## ai-service settings
|
||
|
||
| Variable | Required | Default | Purpose | Secret |
|
||
|---|---|---|---|---|
|
||
| `APP_NAME` | no | `vsf-duoc-thu-ai-service` | FastAPI title | no |
|
||
| `ENVIRONMENT` | no | `local` | Label; sent as `deployment.environment` on OTel resource | no |
|
||
| `QDRANT_URL` | effectively yes | `http://localhost:6333` | Vector store | no |
|
||
| `QDRANT_COLLECTION` | no | `duocthu_v1` | Collection name; the manifest sidecar is `<name>__manifest` | no |
|
||
| `QDRANT_API_KEY` | no | `None` | Qdrant auth | **yes** |
|
||
| `POSTGRES_DSN` | no | `postgresql://duoc_thu:duoc_thu@localhost:5432/duoc_thu` | Traces, turns, feedback. Declared `repr=False` so it is not echoed | **yes** |
|
||
| `EMBEDDING_PROVIDER` | no | `cohere-v4` | `cohere-v4` or `disabled`. Any other value raises at startup | no |
|
||
| `EMBEDDING_DIMENSIONS` | no | `1024` | Must match the corpus manifest or startup fails | no |
|
||
| `EVIDENCE_MINIMUM_SCORE` | no | `0.12` | Dense-route score floor | no |
|
||
| `AWS_REGION` | no | `us-east-1` | Bedrock region | no |
|
||
| `ANSWER_PROVIDER` | no | `disabled` | `disabled` \| `stub` \| `bedrock-converse` \| `bedrock-claude`. **Chooses the operating mode** | no |
|
||
| `ANSWER_MODEL_ID` | no | `deepseek.v3.2` | Bedrock model id | no |
|
||
| `RERANK_ENABLED` | no | `false` | Enables `cohere.rerank-v3-5:0` on the fallback route | no |
|
||
| `METRICS_ENABLED` | no | `true` | Builds the Prometheus exporter | no |
|
||
| `METRICS_TOKEN` | no | `""` | Bearer token for `GET /metrics`; empty = unauthenticated | **yes** |
|
||
| `OTEL_ENABLED` | no | `false` | Turns on OTLP export | no |
|
||
| `OTEL_SERVICE_NAME` | no | `ai-service` | | no |
|
||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | no | `http://localhost:4318/v1/traces` | OTLP/HTTP traces endpoint | no |
|
||
| `OTEL_SAMPLE_RATIO` | no | `1.0` (0.0–1.0) | `TraceIdRatioBased` sampler | no |
|
||
| `ENTITIES_PATH` | in the container | repo-relative `ingestion/data/verified/drug_entities.json` | Drug alias catalog | no |
|
||
| `MAX_WALL_CLOCK_MS` | no | `40000` | Per-turn budget | no |
|
||
| `MAX_LLM_CALLS_PER_TURN` | no | `8` | Per-turn budget | no |
|
||
|
||
`ENTITIES_PATH` needs an explicit value in the container: `config.py`'s default
|
||
resolves two parents up from `apps/ai-service/config.py`, and the image
|
||
flattens `apps/ai-service/` into `/app`, so the depth is wrong. The Dockerfile
|
||
bakes the file to `./ingestion_data/drug_entities.json` and `.env.prod` points
|
||
at it.
|
||
|
||
### Settings that change behaviour, not just tuning
|
||
|
||
Three values are mode switches rather than knobs:
|
||
|
||
| Setting | Effect |
|
||
|---|---|
|
||
| `EMBEDDING_PROVIDER=disabled` | `build_runtime` returns no answer service and no agent. `/v1/rag/query` answers **503**, while `/ready` still answers 200. |
|
||
| `ANSWER_PROVIDER=disabled` | No `RagAgent`, no understanding, no multi-turn. Retrieval-only, single-turn, verbatim quotes. |
|
||
| `EMBEDDING_DIMENSIONS` ≠ manifest | Startup raises `ManifestMismatch` and the process does not come up. |
|
||
|
||
## web settings
|
||
|
||
| Variable | Required | Default | Purpose |
|
||
|---|---|---|---|
|
||
| `API_GATEWAY_URL` | no | — | Preferred upstream; accepts a base URL or a full `/v1/rag/...` URL |
|
||
| `AI_SERVICE_URL` | no | `http://localhost:8000` | Fallback; set to `http://ai-service:8000` in prod Compose |
|
||
|
||
Rate-limit rules are **hard-coded constants** in `middleware.ts`, not
|
||
configuration: `/api/chat` 12/min and 120/hour; `/api/suggest` 120/min.
|
||
|
||
## ingestion settings
|
||
|
||
`ingestion` takes no environment variables. Everything is a CLI flag
|
||
(`--pdf`, `--out`, `--tables`, `--monographs`, `--chunks`, `--provider`,
|
||
`--collection`, `--region`, `--qdrant-url`, `--slice-size`, `--attempts`,
|
||
`--embed-only`). AWS credentials come from the standard boto3 chain.
|
||
|
||
## Deployment-layer configuration
|
||
|
||
| Layer | File | Notes |
|
||
|---|---|---|
|
||
| Production Compose | `infra/docker/docker-compose.prod.yml` | `ai-service` reads `env_file: ../../apps/ai-service/.env.prod` (not in the repo) |
|
||
| Observability overlay | `infra/docker/docker-compose.observability.yml` | Sets `OTEL_ENABLED=true`, `OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces`, `ENVIRONMENT=compose`; reads `GRAFANA_ADMIN_USER` / `GRAFANA_ADMIN_PASSWORD` from the shell |
|
||
| Helm | `values.yaml` + `values-{dev,staging,prod}.yaml` | Maps to a ConfigMap of the same env vars; `POSTGRES_DSN` comes from a Secret |
|
||
| CI | `.github/workflows/deploy.yml` | Uses `EC2_HOST`, `EC2_SSH_KEY`, `GRAFANA_ADMIN_PASSWORD` GitHub secrets |
|
||
|
||
### Helm chart defaults are *not* production defaults
|
||
|
||
`infra/helm/medical-chatbot/values.yaml` ships
|
||
`aiService.config.embeddingProvider: disabled` and `answerProvider: disabled`,
|
||
i.e. a deployment of the chart as-is answers 503 on `/v1/rag/query`. It also
|
||
ships `secret.postgresPassword: duoc_thu` and
|
||
`secret.grafanaAdminPassword: change-me` as literal defaults.
|
||
|
||
## Secrets inventory
|
||
|
||
| Secret | Where it lives | Committed? |
|
||
|---|---|---|
|
||
| PostgreSQL password | `docker-compose.prod.yml` env (`duoc_thu`/`duoc_thu`), Helm `secret.postgresPassword` | **Yes — a default credential is in the repository** |
|
||
| Grafana admin password | `GRAFANA_ADMIN_PASSWORD` GitHub secret → shell env; Helm default `change-me` | Secret value not committed; the placeholder default is |
|
||
| AWS credentials | EC2 instance IAM role | **No** — deliberately; the Compose header comment says so |
|
||
| `QDRANT_API_KEY` | Unset (Qdrant is not exposed) | No |
|
||
| `METRICS_TOKEN` | Unset | No |
|
||
| EC2 host + SSH key | GitHub Actions secrets | No |
|
||
|
||
`git ls-files` shows no `.env` file tracked, and the two IAM documents under
|
||
`infra/aws/iam/` are policy JSON, not credentials. The one real issue is the
|
||
PostgreSQL default credential, which is committed in two places — see
|
||
[16-security.md](16-security.md).
|
||
|
||
## Configuration verified this session
|
||
|
||
`apps/ai-service/.env` (local, gitignored) contains:
|
||
|
||
```
|
||
EMBEDDING_PROVIDER=cohere-v4
|
||
ANSWER_PROVIDER=bedrock-converse
|
||
ANSWER_MODEL_ID=qwen.qwen3-next-80b-a3b
|
||
RERANK_ENABLED=true
|
||
AWS_REGION=us-east-1
|
||
QDRANT_COLLECTION=duocthu_v1
|
||
QDRANT_URL=<local>
|
||
```
|
||
|
||
Note the drift: the **code default** for `ANSWER_MODEL_ID` is `deepseek.v3.2`,
|
||
the **local `.env`** uses `qwen.qwen3-next-80b-a3b`, and the **production value
|
||
is unverifiable from the repository** because `.env.prod` is not committed. Any
|
||
statement about which model production runs would be a guess.
|