# Deploy AI Search (value indexing)

Deploy the field value indexing service so abbreviations in questions can match actual data.

部署说明 · 模块: deploy · 管理人员 · 部署形态：私有部署 · 已确认产品版本：资料未说明 · 来源：现有文档

AI indexing is provided by a separate search service. It indexes string field values to match abbreviations in questions to actual data. Private deployment requires this additional service and its address and key configured in the main service.

**Without aisearch, this entire capability is unavailable**: enabling AI indexing for a field is rejected with a message that the AI Search index is not enabled, and no value matching occurs when asking questions. Other features are unaffected.

## Prerequisites

| Item             | Requirement                                                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Basic deployment | Running after following [Private deployment (Docker)](https://docs.asktable.com/en/deploy/docker)                                          |
| Permissions      | A role that can edit data source configuration in the current project                                                                      |
| Key              | Prepare a random string of at least 16 bytes as the master key                                                                             |
| Outbound access  | Not required. aisearch is self-contained and makes no outbound calls at runtime, making it suitable for fully offline or internal networks |

## Steps

**Add the aisearch service**

Add this service to `docker-compose.yaml`:

```yaml
services:
  # aisearch engine: storage and retrieval for value indexes
  asktable-aisearch:
    image: registry.cn-shanghai.aliyuncs.com/dminfra/aisearch:v1.12.8
    container_name: asktable-aisearch
    restart: unless-stopped
    environment:
      MEILI_MASTER_KEY: CHANGE_ME_MIN_16_BYTES   # At least 16 bytes; replace with your own random string
      MEILI_ENV: production                            # Production mode: enforce authentication, disable search preview
      MEILI_NO_ANALYTICS: "true"                       # Disable telemetry
    volumes:
      - ./aisearch_data:/meili_data                    # Persist index data
```

Only `asktable` accesses it over the internal Compose network; do not add `ports`.

**Configure the main service to use it**

Add two variables to the `asktable` service's `environment` and include the new service in `depends_on`:

```yaml
services:
  asktable:
    depends_on:
      - asktable-aisearch
    environment:
      AISEARCH_HOST: http://asktable-aisearch:7700
      AISEARCH_MASTER_KEY: CHANGE_ME_MIN_16_BYTES   # Must exactly match MEILI_MASTER_KEY above
```

**Recreate the containers**

```bash
docker compose up -d
```

**Confirm the main service recognizes it**

```bash
docker compose logs asktable | grep "AI Search Host"
```

`AI Search Host : http://asktable-aisearch:7700` indicates successful configuration; `AI Search Host : disabled` means one of the two variables is empty.

Then check the service directly:

```bash
docker compose exec asktable curl -sS -H "Authorization: Bearer CHANGE_ME_MIN_16_BYTES" http://asktable-aisearch:7700/health
```

## Build and rebuild indexes

Setting both variables makes the capability available, but indexes must be built separately:

- **Enable per field**: Main navigation on the left → “More” → “Data sources” → select a data source card → select a table in the left tree → click a field row to expand its detail panel → AI indexing switch in the top-left corner. A status icon appears to the right of the switch: a green check means indexing succeeded, and a red cross means it failed.
- **Build for the entire data source**: Data source page top bar → “Settings” → “Index maintenance” → “Build Value Index”. The build starts in the background and takes effect automatically when complete.
- **Fill in field embeddings**: “Rebuild Embedding” in the same section fills in missing semantic field vectors; this is separate from value indexing.

Indexes are built asynchronously by background tasks using the existing `asktable-redis` queue; no additional component is required.

## Key constraints

| Item                                  | Value or default                                                                                         | Where to change it                                                              |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `MEILI_MASTER_KEY`                    | Example value; with `MEILI_ENV: production`, the service refuses to start if it is shorter than 16 bytes | `asktable-aisearch.environment`                                                 |
| `AISEARCH_MASTER_KEY`                 | Must exactly match `MEILI_MASTER_KEY`                                                                    | `asktable.environment`                                                          |
| `AISEARCH_HOST`                       | `http://asktable-aisearch:7700`                                                                          | Same as above                                                                   |
| Index data directory                  | `./aisearch_data` (`/meili_data` inside the container)                                                   | `volumes` in `docker-compose.yaml`                                              |
| Public ports                          | None                                                                                                     | Do not add `ports` to `asktable-aisearch`                                       |
| Indexed fields                        | String fields; long text, dates, and numbers are not indexed                                             | —                                                                               |
| Value indexing fields per data source | Default: 10                                                                                              | Avatar → “System settings” → “Data sources” → Maximum fields for value indexing |
| Unique values per field               | Default: 50000                                                                                           | Same section → Maximum unique values indexed per field                          |
| Trigger                               | Per-field switch or “Build Value Index” for the entire data source                                       | Data source → “Settings” → “Index maintenance”                                  |

## Troubleshooting

| Symptom                                                                 | How to identify it                                                                                       | Action                                                                                                                                                                     |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enabling AI indexing is rejected with “AI Search index not enabled”     | `docker compose logs asktable` shows `AI Search Host : disabled`                                         | Either `AISEARCH_HOST` or `AISEARCH_MASTER_KEY` is empty; fill it in and recreate the container                                                                            |
| The main service recognizes the address, but the feature is unavailable | A request to `/health` with the key returns an authentication failure                                    | The keys differ; make `AISEARCH_MASTER_KEY` exactly match `MEILI_MASTER_KEY`                                                                                               |
| aisearch container restarts repeatedly                                  | `docker compose logs asktable-aisearch` reports an insufficient key length                               | Extend the key to at least 16 bytes                                                                                                                                        |
| All indexes are lost after restart                                      | `asktable-aisearch` has no `./aisearch_data` mount in `docker compose ps`                                | Add the volume mount; `docker compose down -v` deletes volumes too, so do not use it in production                                                                         |
| A red cross appears after enabling the switch                           | The “AI index details” panel in field details shows a failed status and a rejection reason at the bottom | Choose a field based on the reason: use a lower-cardinality column if the unique-value limit was exceeded, or a short-text column if the average-length limit was exceeded |
| The whole-source build button is disabled                               | The data source is not in a normal, usable state                                                         | Wait for metadata synchronization to finish, or resolve the synchronization failure first                                                                                  |
| The completed index has not taken effect                                | A build-started message appeared, but the data in the details has not changed                            | Building is a background task; wait for completion. The page refreshes the status automatically                                                                            |

## Next steps

- [AI indexing](https://docs.asktable.com/en/data/ai-search) — How to use it and choose fields
- [Private deployment (Docker)](https://docs.asktable.com/en/deploy/docker) — Main service deployment and troubleshooting
- [Deploy the message gateway](https://docs.asktable.com/en/deploy/feishu-gateway) — Let the team ask questions in Feishu direct messages and groups
- [Deployment overview](https://docs.asktable.com/en/deploy/overview) — Optional components and rollout order
