# Cấu hình và mô hình dữ liệu

> Loại chính: Reference

## Runtime environment

| Biến | Mặc định | Ý nghĩa |
|---|---|---|
| `APP_NAME` | `vsf-duoc-thu-ai-service` | tên app |
| `ENVIRONMENT` | `local` | nhãn môi trường |
| `QDRANT_URL` | `http://localhost:6333` | vector store |
| `QDRANT_COLLECTION` | `duocthu_v1` | corpus query |
| `QDRANT_API_KEY` | rỗng | secret cho remote Qdrant |
| `POSTGRES_DSN` | DSN local | trace, conversation, feedback; coi là secret |
| `EMBEDDING_PROVIDER` | `cohere-v4` | runtime hỗ trợ `cohere-v4`, `disabled` |
| `EMBEDDING_DIMENSIONS` | `1024` | phải khớp manifest |
| `EVIDENCE_MINIMUM_SCORE` | `0.12` | cổng evidence |
| `AWS_REGION` | `us-east-1` | Bedrock region |
| `ANSWER_PROVIDER` | `disabled` | `disabled`, `stub`, `bedrock-claude`, `bedrock-converse` |
| `ANSWER_MODEL_ID` | `deepseek.v3.2` | generation model |
| `RERANK_ENABLED` | `false` | rerank similarity/overview |
| `METRICS_ENABLED` | `true` | bật metrics nếu package có |
| `METRICS_TOKEN` | rỗng | bảo vệ `/metrics` |
| `OTEL_ENABLED` | `false` | bật OTel |
| `OTEL_SERVICE_NAME` | `ai-service` | service name |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318/v1/traces` | OTLP HTTP |
| `OTEL_TRACES_SAMPLER_ARG` | `1.0` | sample ratio |
| `ENTITIES_PATH` | tính từ project | alias catalog |
| `MAX_WALL_CLOCK_MS` | `40000` | budget mỗi turn |
| `MAX_LLM_CALLS_PER_TURN` | `8` | trần model calls |

`EMBEDDING_PROVIDER=disabled` không tạo RAG runtime. `ANSWER_PROVIDER=disabled`
không có agent/generation đầy đủ. `stub` chỉ phục vụ local test. Không commit DSN,
AWS credential, Qdrant key hoặc production env file.

## Chunk schema v4

- Identity: `chunk_id`, `drug_id`, `drug_name`.
- Section/content: `section_key`, `section_display_name`, `text`, `source_text`,
  `context_labels`, `heading_physical_page`.
- Provenance: `source_page_range`, `printed_page_range`.
- Partition: `part_index`, `part_count`, `est_tokens`, `oversized`.
- Classification/safety: `atc_codes`, `chunk_kind`, `attachments`,
  `has_quarantined_content`.

`chunk_kind` là `prose` hoặc `block_descriptor`. Attachment giữ `block_id`, kind,
shape, physical/printed page, bbox, source crop, quarantine flag và header row.

## Qdrant

Point ID là UUID5 ổn định từ `chunk_id`, giúp load idempotent. Payload index gồm
`chunk_id`, `drug_id`, `section_key`, `atc_codes`, `chunk_kind` và
`has_quarantined_content`.

Sidecar manifest giữ `corpus_sha256`, `chunk_count`, `model_id`, `dimensions`,
`input_kind`, `provider`, `distance`. Manifest mismatch làm ai-service từ chối startup.

## PostgreSQL

Migration là nguồn chuẩn cho column/index. Các nhóm dữ liệu gồm retrieval trace,
conversation turns, correlation/OTel fields và answer feedback.