Skip to content

docs(vector-store): 完善向量库配置使用文档 #595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zxuexingzhijie merged 1 commit into from
Aug 6, 2026
Merged

docs(vector-store): 完善向量库配置使用文档 #595

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 74 additions & 5 deletions docs/DEVELOPER_GUIDE-en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,13 +178,16 @@ Configuration prefix: `spring.ai.alibaba.data-agent.vector-store`

| Configuration Item | Description | Default Value |
|-------------------|-------------|---------------|
| `default-similarity-threshold` | Global default similarity threshold | 0.4 |
| `table-similarity-threshold` | Table recall similarity threshold | 0.2 |
| `default-similarity-threshold` | Global default similarity threshold (used by business knowledge, agent knowledge, etc.) | 0.4 |
| `table-similarity-threshold` | Table recall similarity threshold (kept low to avoid missing tables during recall) | 0.2 |
| `batch-del-topk-limit` | Maximum documents for batch deletion | 5000 |
| `default-topk-limit` | Global default max documents returned (currently only used by business knowledge and agent knowledge) | 8 |
| `table-topk-limit` | Maximum documents for table recall | 10 |
| `enable-hybrid-search` | Enable hybrid search | false |
| `elasticsearch-min-score` | ES keyword search minimum score threshold | 0.5 |
| `embedding-dimension` | Expected embedding dimension for the persistent vector store; must match the embedding model's output dimension. A value of `0` disables the check (the in-memory store defaults to 0) | 0 |
| `enable-hybrid-search` | Enable hybrid search (vector retrieval + ES keyword retrieval); only effective with Elasticsearch | false |
| `hybrid-search-timeout-ms` | Maximum wait time (ms) for each retrieval branch in hybrid search | 3000 |
| `elasticsearch-min-score` | ES keyword search minimum score threshold, used to filter out low-relevance documents | 0.5 |
| `file-path` | Local serialization file path for `SimpleVectorStore` (in-memory store only) | `./vectorstore/vectorstore.json` |

#### Vector Store Dependency Extension

Expand All @@ -202,8 +205,74 @@ The project uses in-memory vector store (`SimpleVectorStore`) by default. To use

2. **Configure Properties**: Add the corresponding vector store connection configuration in `application.yml`. For specific parameters, refer to [Spring AI Official Documentation](https://springdoc.cn/spring-ai/api/vectordbs.html).

2. **Configure `spring.ai.vectorstore.type`**. You can find the specific value after importing the vector store starter above by searching for `VectorStoreAutoConfiguration` auto-configuration class. For example, for `es` it's `ElasticsearchVectorStoreAutoConfiguration`, and you can see that `spring.ai.vectorstore.type` expects `elasticsearch`.
3. **Configure `spring.ai.vectorstore.type`**. You can find the specific value after importing the vector store starter above by searching for the `VectorStoreAutoConfiguration` auto-configuration class. For example, for `es` it's `ElasticsearchVectorStoreAutoConfiguration`, and you can see that `spring.ai.vectorstore.type` expects `elasticsearch`.

4. **Configure `embedding-dimension`**: When using a persistent vector store, set `spring.ai.alibaba.data-agent.vector-store.embedding-dimension` to match your embedding model's output dimension (e.g. `1024`). This validates the dimension at startup and avoids retrieval failures after documents are written.

#### Ready-to-Use Configuration Examples

The project ships two ready-to-activate vector store example profiles under `data-agent-management/src/main/resources/`. Activate the corresponding profile via `spring.profiles.active` or the `SPRING_PROFILES_ACTIVE` environment variable — no manual connection configuration required.

**Milvus (`application-milvus.yml`)**

```yaml
spring:
ai:
vectorstore:
type: milvus
milvus:
client:
host: ${MILVUS_HOST:127.0.0.1}
port: ${MILVUS_PORT:19530}
database-name: ${MILVUS_DATABASE:default}
collection-name: ${MILVUS_COLLECTION:vector_store}
embedding-dimension: ${MILVUS_DIMENSION:1024}
initialize-schema: true
alibaba:
data-agent:
vector-store:
embedding-dimension: ${MILVUS_DIMENSION:1024}
```

The `spring-ai-starter-vector-store-milvus` dependency is already bundled in `data-agent-management/pom.xml`, so no extra dependency is needed — just activate the profile:

```bash
export SPRING_PROFILES_ACTIVE=milvus
# Optional: override the default connection info
export MILVUS_HOST=127.0.0.1
export MILVUS_PORT=19530
```

**Elasticsearch (`application-elasticsearch.yml`)**

```yaml
spring:
elasticsearch:
uris: ${ELASTICSEARCH_URIS:http://127.0.0.1:9200}
username: ${ELASTICSEARCH_USERNAME:}
password: ${ELASTICSEARCH_PASSWORD:}
ai:
vectorstore:
type: elasticsearch
elasticsearch:
index-name: ${ELASTICSEARCH_INDEX_NAME:spring-ai-document-index}
dimensions: ${ELASTICSEARCH_DIMENSIONS:1024}
initialize-schema: ${ELASTICSEARCH_INITIALIZE_SCHEMA:true}
alibaba:
data-agent:
vector-store:
embedding-dimension: ${ELASTICSEARCH_DIMENSIONS:1024}
```

The `spring-ai-starter-vector-store-elasticsearch` dependency is already bundled in `data-agent-management/pom.xml`, so no extra dependency is needed — just activate the profile:

```bash
export SPRING_PROFILES_ACTIVE=elasticsearch
# Optional: override the default connection info
export ELASTICSEARCH_URIS=http://127.0.0.1:9200
```

> Tip: Elasticsearch supports hybrid search. After activating the ES profile, set `spring.ai.alibaba.data-agent.vector-store.enable-hybrid-search` to `true` to enable the weighted fusion of vector retrieval and keyword retrieval.

#### ES Schema Configuration Example
Below is the Elasticsearch Schema structure. Other vector stores (like Milvus, PGVector) can reference this structure to create their Schema, paying special attention to the data types of fields in `metadata`.
Expand Down
79 changes: 74 additions & 5 deletions docs/DEVELOPER_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,13 +178,16 @@ public class AgentVectorStoreService {

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `default-similarity-threshold` | 全局默认相似度阈值 | 0.4 |
| `table-similarity-threshold` | 召回表的相似度阈值 | 0.2 |
| `default-similarity-threshold` | 全局默认相似度阈值（用于业务知识、智能体知识等） | 0.4 |
| `table-similarity-threshold` | 召回表的相似度阈值（设置较低以尽量避免表召回遗漏） | 0.2 |
| `batch-del-topk-limit` | 批量删除时的最大文档数量 | 5000 |
| `default-topk-limit` | 全局默认查询返回的最大文档数量（目前只有业务知识和智能体知识在使用） | 8 |
| `table-topk-limit` | 召回表的最大文档数量 | 10 |
| `enable-hybrid-search` | 是否启用混合搜索 | false |
| `elasticsearch-min-score` | ES关键词搜索的最小分数阈值 | 0.5 |
| `embedding-dimension` | 持久化向量库期望的向量维度校验值，需与嵌入模型输出维度一致；设为 `0` 时关闭校验（内存向量库默认即为 0） | 0 |
| `enable-hybrid-search` | 是否启用混合搜索（向量检索 + ES 关键词检索），仅在使用 Elasticsearch 时生效 | false |
| `hybrid-search-timeout-ms` | 混合检索中每个检索分支的最大等待时间（毫秒） | 3000 |
| `elasticsearch-min-score` | ES 关键词搜索的最小分数阈值，用于过滤相关性较低的文档 | 0.5 |
| `file-path` | `SimpleVectorStore` 本地序列化文件地址（仅内存向量库使用） | `./vectorstore/vectorstore.json` |

#### 向量库依赖扩展

Expand All @@ -202,8 +205,74 @@ public class AgentVectorStoreService {

2. **配置属性**: 在 `application.yml` 中添加对应向量库的连接配置。具体参数请参考 [Spring AI 官方文档](https://springdoc.cn/spring-ai/api/vectordbs.html)。

2. **配置 `spring.ai.vectorstore.type`**。具体填写的值可以在引入上面的向量库starter后自行搜索 `VectorStoreAutoConfiguration`自动配置类，比如`es`的是`ElasticsearchVectorStoreAutoConfiguration`，该类里面可以看见`spring.ai.vectorstore.type`期望的是`elasticsearch`。
3. **配置 `spring.ai.vectorstore.type`**。具体填写的值可以在引入上面的向量库 starter 后自行搜索 `VectorStoreAutoConfiguration` 自动配置类，比如 `es` 的是 `ElasticsearchVectorStoreAutoConfiguration`，该类里面可以看见 `spring.ai.vectorstore.type` 期望的是 `elasticsearch`。

4. **配置 `embedding-dimension`**: 使用持久化向量库时，建议将 `spring.ai.alibaba.data-agent.vector-store.embedding-dimension` 设置为与嵌入模型输出维度一致的值（如 `1024`），以便启动时校验维度是否匹配，避免写入后检索异常。

#### 开箱即用的配置示例

项目已内置两个可直接激活的向量库示例 Profile，位于 `data-agent-management/src/main/resources/`。通过 `spring.profiles.active` 或环境变量 `SPRING_PROFILES_ACTIVE` 激活对应 Profile 即可，无需手动编写连接配置。

**Milvus (`application-milvus.yml`)**

```yaml
spring:
ai:
vectorstore:
type: milvus
milvus:
client:
host: ${MILVUS_HOST:127.0.0.1}
port: ${MILVUS_PORT:19530}
database-name: ${MILVUS_DATABASE:default}
collection-name: ${MILVUS_COLLECTION:vector_store}
embedding-dimension: ${MILVUS_DIMENSION:1024}
initialize-schema: true
alibaba:
data-agent:
vector-store:
embedding-dimension: ${MILVUS_DIMENSION:1024}
```

`spring-ai-starter-vector-store-milvus` 依赖已包含在 `data-agent-management/pom.xml` 中，无需额外引入，激活 Profile 即可：

```bash
export SPRING_PROFILES_ACTIVE=milvus
# 可选：覆盖默认连接信息
export MILVUS_HOST=127.0.0.1
export MILVUS_PORT=19530
```

**Elasticsearch (`application-elasticsearch.yml`)**

```yaml
spring:
elasticsearch:
uris: ${ELASTICSEARCH_URIS:http://127.0.0.1:9200}
username: ${ELASTICSEARCH_USERNAME:}
password: ${ELASTICSEARCH_PASSWORD:}
ai:
vectorstore:
type: elasticsearch
elasticsearch:
index-name: ${ELASTICSEARCH_INDEX_NAME:spring-ai-document-index}
dimensions: ${ELASTICSEARCH_DIMENSIONS:1024}
initialize-schema: ${ELASTICSEARCH_INITIALIZE_SCHEMA:true}
alibaba:
data-agent:
vector-store:
embedding-dimension: ${ELASTICSEARCH_DIMENSIONS:1024}
```

`spring-ai-starter-vector-store-elasticsearch` 依赖已包含在 `data-agent-management/pom.xml` 中，无需额外引入，激活 Profile 即可：

```bash
export SPRING_PROFILES_ACTIVE=elasticsearch
# 可选：覆盖默认连接信息
export ELASTICSEARCH_URIS=http://127.0.0.1:9200
```

> 提示：Elasticsearch 支持混合检索。激活 ES Profile 后，再将 `spring.ai.alibaba.data-agent.vector-store.enable-hybrid-search` 设为 `true` 即可启用向量检索与关键词检索的混合融合策略。

#### ES Schema 配置示例
以下为 Elasticsearch 的 Schema 结构。其他向量库（如 Milvus, PGVector）可参考此结构建立 Schema，尤其要注意 `metadata` 中的字段数据类型。
Expand Down
2 changes: 2 additions & 0 deletions docs/QUICK_START-en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,8 @@ Below is the ES schema structure. For other vector stores like Milvus, PG, etc.,
### 2.7 Replace Vector Store Implementation

> To replace the default in-memory vector store (for example, with PGVector or Milvus), see [Developer Guide - Vector Store Dependency Extension](DEVELOPER_GUIDE-en.md#vector-store-dependency-extension).
>
> The project ships two ready-to-use example profiles, `application-milvus.yml` and `application-elasticsearch.yml`. Switch quickly with `SPRING_PROFILES_ACTIVE=milvus` (or `elasticsearch`); see [Developer Guide - Ready-to-Use Configuration Examples](DEVELOPER_GUIDE-en.md#ready-to-use-configuration-examples).

### 2.8 Configure the Python Sandbox

Expand Down
2 changes: 2 additions & 0 deletions docs/QUICK_START.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,8 @@ spring:
### 2.7 替换vector-store的实现类

> 关于如何替换默认的内存向量库（如使用 PGVector、Milvus 等），请参考 [开发者指南 - 向量库依赖扩展](DEVELOPER_GUIDE.md#向量库依赖扩展)。
>
> 项目已内置 `application-milvus.yml` 与 `application-elasticsearch.yml` 两个开箱即用的示例 Profile，通过 `SPRING_PROFILES_ACTIVE=milvus`（或 `elasticsearch`）即可快速切换，详见 [开发者指南 - 开箱即用的配置示例](DEVELOPER_GUIDE.md#开箱即用的配置示例)。

### 2.8 配置 Python 沙盒

Expand Down
Loading