> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Qdrant

> 配置 Qdrant 向量数据库服务

## Qdrant

Qdrant 是一个向量相似性搜索引擎，它提供可用于生产环境的服务。

xParse支持 Qdrant Local、 Qdrant client-sever 以及 Qdrant Cloud的连接。

### 参数说明

| 参数                | 类型        | 必填 | 说明                                    |
| ----------------- | --------- | -- | ------------------------------------- |
| `type`            | `string`  | 是  | 固定为 `"qdrant"`                        |
| `url`             | `string`  | 是  | Qdrant 的连接地址，如`http://localhost:6333` |
| `collection_name` | `string`  | 是  | 集合（Collection）名称                      |
| `dimension`       | `integer` | 是  | 向量维度，必须与 embed 模型维度一致（当前为 1024）       |
| `api_key`         | `string`  | 否  | Qdrant Cloud API Key                  |
| `prefer_grpc`     | `boolean` | 否  | 是否优先使用 gRPC（默认 False）                 |

### 如何获取 Qdrant Cloud 鉴权参数

1. **注册 Qdrant Cloud 账号**：
   * 访问 [Qdrant Cloud 官网](https://qdrant.tech/cloud)
   * 注册并登录账号

2. **创建集群**：
   * 在 Qdrant Cloud 控制台创建新的集群
   * 选择合适的地域和规格
   * 等待集群创建完成

3. **获取连接信息**：
   * 在集群详情页查看"连接地址"（Endpoint）
   * 格式：`https://xxxxxxxxx.xxxxx.xxxxx.cloud.qdrant.io`

4. **获取 API Key**：
   * 进入"API Keys"页面
   * 创建新的 API Key 或使用现有 Key
   * 保存 API Key 值（注意：API Key 只显示一次，请妥善保存）

5. **创建集合**（可选）：
   * xParse client 会自动创建集合，但您也可以预先在控制台创建
   * 确保集合的向量维度与 embed 模型一致（1024 维）
   * xParse client 需要使用 `record_id` 索引，如果该索引不存在会静默创建

### 配置示例

```python theme={null}
from xparse_client import QdrantDestination

destination = QdrantDestination(
    url='https://xxxxxxxxx.xxxxx.xxxxx.cloud.qdrant.io',  # Qdrant Cloud 连接地址
    collection_name='my_collection',      # 集合名称
    dimension=1024,                      # 向量维度
    api_key='your-qdrant-api-key'        # Qdrant Cloud API Key
)
```

### 使用示例

```python theme={null}
from xparse_client import QdrantDestination, Pipeline

destination = QdrantDestination(
    url='https://xxxxxxxxx.xxxxx.xxxxx.cloud.qdrant.io',
    collection_name='my_collection',
    dimension=1024,
    api_key='your-qdrant-api-key'
)

# ... 其他配置

pipeline = Pipeline(
    source=source,
    destination=destination,
    # ...其他配置
)
pipeline.run()
```

### 数据 Schema

| 字段名         | 类型                  | 说明           |
| ----------- | ------------------- | ------------ |
| `id`        | VARCHAR(128)        | 元素唯一标识符（主键）  |
| `vectors`   | FLOAT\_VECTOR(1024) | 向量嵌入（1024 维） |
| `text`      | VARCHAR(65535)      | 元素文本内容       |
| `record_id` | VARCHAR(128)        | 记录 ID        |
| `metadata`  | JSON                | 元数据信息（动态字段）  |

### 向量检索示例

```python theme={null}
from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue

client = QdrantClient(
    url='https://xxxxxxxxx.xxxxx.xxxxx.cloud.qdrant.io',
    api_key='your-qdrant-api-key'
)

query_vector = [0.1, 0.2, 0.3, ...]  # 1024 维向量

search_result = client.query_points(
    collection_name="test_collection",
    query=query_vector,
    query_filter=Filter(
        must=[FieldCondition(key="city", match=MatchValue(value="London"))]
    ),
    with_payload=True,
    limit=3,
).points

print(search_result)
```

### 参考文档

* [Qdrant 文档](https://qdrant.tech/documentation/)