# https://github.com/qdrant/qdrant-client 项目说明书

生成时间：2026-06-28 21:36:34 UTC

## 目录

- [Project Overview & Architecture](#page-1)
- [Connection Modes, Transports & Authentication](#page-2)
- [Data Operations, Uploaders & Type Conversions](#page-3)
- [Inference API, FastEmbed & Troubleshooting](#page-4)

<a id='page-1'></a>

## Project Overview & Architecture

### 相关页面

相关主题：[Connection Modes, Transports & Authentication](#page-2), [Data Operations, Uploaders & Type Conversions](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/qdrant/qdrant-client/blob/main/README.md)
- [qdrant_client/http/api/search_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/search_api.py)
- [qdrant_client/http/api/snapshots_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/snapshots_api.py)
- [qdrant_client/http/models/models.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/models/models.py)
- [qdrant_client/http/api/collections_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py)
- [qdrant_client/http/api/aliases_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/aliases_api.py)
- [qdrant_client/http/api/distributed_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/distributed_api.py)
- [qdrant_client/http/api/indexes_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/indexes_api.py)
- [qdrant_client/http/api/points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py)
- [qdrant_client/http/api/service_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/service_api.py)
- [qdrant_client/http/api/beta_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/beta_api.py)
</details>

# 项目概述与架构

## 项目定位与目标

`qdrant-client` 是 [Qdrant](https://github.com/qdrant/qdrant) 向量搜索引擎官方维护的 **Python 客户端库**，以 PyPI 包的形式发布（参考 [README.md:1-12](https://github.com/qdrant/qdrant-client/blob/main/README.md)）。仓库同时提供 **同步与异步** 两套高层 API，向下封装基于 HTTP 与 gRPC 的底层传输，对外暴露统一的领域模型（如 `Collection`、`Point`、`SearchRequest` 等），从而让 Python 用户以最少的样板代码完成向量检索与数据写入。库本身并不包含向量数据库实现，而是与独立部署的 Qdrant 服务进行通信；最新版 v1.18.0 已支持 named vector、turbo quantization 等新特性（见社区变更日志）。

## 整体架构

仓库遵循「生成式 + 分层」结构：底层是自动生成的 HTTP API 模块，中间是 Pydantic 数据模型，顶层由 `QdrantClient` / `AsyncQdrantClient` 之类的便利封装使用。下图展示了从用户调用到 Qdrant 服务端的关键链路：

```mermaid
flowchart TD
    User[用户代码] --> QC[QdrantClient / AsyncQdrantClient]
    QC -->|高层方法| APIMod[http/api/*_api.py 业务模块]
    APIMod -->|jsonable_encoder| Models[http/models/models.py Pydantic 模型]
    APIMod -->|request| Client[ApiClient / AsyncApiClient]
    Client -->|HTTPS + JSON| Qdrant[(Qdrant 服务)]
    Qdrant --> Client
    Client --> Models
    Models --> QC
    QC --> User
```

各模块的职责清晰：

| 模块路径 | 职责 |
|---|---|
| `qdrant_client/http/api/*.py` | 按业务域拆分的 HTTP 接口（如 collections、points、search、aliases、indexes、snapshots、distributed、service、beta） |
| `qdrant_client/http/models/models.py` | 基于 Pydantic 的请求/响应模型与枚举 |
| `qdrant_client/http/api_client.py` | 底层 HTTP 客户端（同步/异步） |
| `qdrant_client/qdrant_client.py` | 同步高层封装入口 |
| `qdrant_client/async_qdrant_client.py` | 异步高层封装入口 |

资料来源：[qdrant_client/http/api/search_api.py:1-12](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/search_api.py)、[qdrant_client/http/models/models.py:1-10](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/models/models.py)、[README.md:1-12](https://github.com/qdrant/qdrant-client/blob/main/README.md)。

## 关键 API 模块划分

仓库在 `qdrant_client/http/api` 目录下按 REST 资源划分模块，每个模块都同时提供 `_SearchApi` 风格的构建方法、`AsyncSearchApi` 异步类与 `SyncSearchApi` 同步类，实现同一份生成代码的两套调用风格：

- **集合管理**：[collections_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py) 提供 `collection_exists`、`create_collection` 等方法（如 `_build_for_collection_exists`）。
- **向量与点操作**：[points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py) 提供 `batch_update`、清空 payload 等写操作入口。
- **检索与发现**：[search_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/search_api.py) 暴露 `search_points`、`discover_points`、`discover_batch_points` 等检索/推荐接口。
- **索引**：[indexes_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/indexes_api.py) 处理字段索引的创建与删除。
- **别名 / 快照 / 集群 / 服务 / 实验性接口**：分别位于 [aliases_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/aliases_api.py)、[snapshots_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/snapshots_api.py)、[distributed_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/distributed_api.py)、[service_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/service_api.py)、[beta_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/beta_api.py)。

每个 `_build_for_*` 方法会构造 `path_params`、`query_params`、`headers`、`body`，最终调用 `self.api_client.request(...)` 完成请求。资料来源：[qdrant_client/http/api/search_api.py:1-100](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/search_api.py)、[qdrant_client/http/api/collections_api.py:1-30](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py)。

## 数据模型与序列化

所有请求/响应都通过 Pydantic `BaseModel` 描述，并通过 `jsonable_encoder` 序列化为 JSON。`jsonable_encoder` 会判断 Pydantic 主版本（v1 用 `model.json`，v2 用 `model_dump_json`），并默认开启 `by_alias=True`、`exclude_unset=True`、`exclude_none=True`，确保请求体只携带有效字段。资料来源：[qdrant_client/http/api/search_api.py:1-30](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/search_api.py)、[qdrant_client/http/models/models.py:1-30](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/models/models.py)。

社区曾报告 `models.py` 中部分描述字符串使用了非法的转义序列，触发 `SyntaxWarning: invalid escape sequence '\&'`（issue #983），这暴露了生成代码中字符串声明的小问题；用户在受影响版本中可改用原始字符串或忽略该警告。

## 常见失败模式与社区关注点

根据社区讨论，开发者最常遇到的几种异常如下：

1. **读取超时**：`ResponseHandlingException: The read operation timed out`（issue #380），通常源于默认超时与请求体规模不匹配，建议增大客户端 `timeout` 参数或减小批次。
2. **gRPC SSL 握手失败**：`SSL_ERROR_SSL: WRONG_VERSION_NUMBER`（issue #770），常见于客户端使用了 `https://` 风格前缀去连接裸 gRPC 端口，需检查是否在 `QdrantClient` 中启用了 gRPC 以及端口是否与协议匹配。
3. **`upload_collection` 静默失败**：数据维度与集合配置不一致时不会抛错（issue #17），推荐在使用前显式校验向量维度。
4. **异步 API 缺失的演进**：早期社区呼吁更易用的 `AsyncQdrantClient`（issue #157），现已随 v1.18.0 系列版本得到完善。

## See Also

- 集合与索引：[Project Overview & Architecture](/wiki/Project-Overview-&-Architecture)
- 向量检索接口：[Search & Recommendation API](/wiki/Search-&-Recommendation-API)
- 数据模型参考：[Pydantic Models Reference](/wiki/Pydantic-Models-Reference)

---

<a id='page-2'></a>

## Connection Modes, Transports & Authentication

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [Inference API, FastEmbed & Troubleshooting](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [qdrant_client/connection.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/connection.py)
- [qdrant_client/qdrant_remote.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/qdrant_remote.py)
- [qdrant_client/async_qdrant_remote.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/async_qdrant_remote.py)
- [qdrant_client/local/qdrant_local.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/local/qdrant_local.py)
- [qdrant_client/local/async_qdrant_local.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/local/async_qdrant_local.py)
- [qdrant_client/http/configuration.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/configuration.py)
- [qdrant_client/http/api_client.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api_client.py)
- [qdrant_client/http/api/service_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/service_api.py)
- [qdrant_client/http/api/collections_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py)
</details>

# Connection Modes, Transports & Authentication

## 概述

`qdrant-client` 是 Qdrant 向量数据库的官方 Python 客户端，它在客户端侧抽象了多种连接模式与传输协议，使用户能够以统一的 API 与远程 Qdrant 服务或本地嵌入式实例进行交互。本页系统梳理 `QdrantClient` 与 `AsyncQdrantClient` 支持的连接模式（远程 / 本地）、传输层（HTTP REST 与 gRPC）以及身份验证机制，并结合社区中频繁出现的超时、SSL 握手与异步使用等议题给出实践指引。

资料来源：[qdrant_client/qdrant_remote.py:1-1]()、[qdrant_client/async_qdrant_remote.py:1-1]()

## 连接模式

### 远程模式（Remote Mode）

远程模式下，客户端通过 HTTP REST 与 gRPC 双通道与 Qdrant Server 通信。HTTP 通道承担大部分元数据与向量 CRUD 操作，gRPC 通道负责高性能的 search / recommend / scroll 等向量检索请求。客户端在内部组合这两条通道，对外只暴露 `QdrantClient` / `AsyncQdrantClient` 这一高层接口。

资料来源：[qdrant_client/qdrant_remote.py:1-1]()、[qdrant_client/async_qdrant_remote.py:1-1]()

### 本地模式（Local Mode / Embedded）

`QdrantClient(":memory:")` 或传入本地持久化路径时启用嵌入式模式。该模式不依赖任何外部 Server，库内部直接启动并管理一个本地 Qdrant 实例，适合测试、教学与离线实验。注意本地模式的 `values_count` 等统计信息历史上曾与服务端语义不一致，参见 issue #1191（已在 v1.18.0 修复）。

资料来源：[qdrant_client/local/qdrant_local.py:1-1]()、[qdrant_client/local/async_qdrant_local.py:1-1]()

## 传输层架构

### HTTP REST 通道

HTTP 通道通过 [qdrant_client/http/api_client.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api_client.py) 中的 `ApiClient` / `AsyncApiClient` 发送请求。每个功能模块（collections、points、search、aliases、snapshots、service、distributed、indexes、beta）对应一个 `_XxxApi` 内部类以及 `SyncXxxApi` / `AsyncXxxApi` 两个对外包装类，内部类通过 `_build_for_*` 方法构造请求（设置路径参数 `path_params`、查询参数 `query_params`、请求头 `headers`、JSON body），再委托 `api_client.request(...)` 统一发起。

资料来源：[qdrant_client/http/api/collections_api.py:1-1]()、[qdrant_client/http/api/service_api.py:1-1]()、[qdrant_client/http/api/search_api.py:1-1]()

### gRPC 通道

gRPC 通道由 `qdrant_remote.py` 直接持有，封装了 Qdrant 官方 `qdrant.proto` 生成的高吞吐 API，主要承担向量检索与批量写入等场景。

### 请求构造示意

```mermaid
flowchart LR
    A[QdrantClient 高级方法] --> B[_build_for_*]
    B --> C[path_params / query_params / headers]
    B --> D[jsonable_encoder body]
    C --> E[ApiClient.request]
    D --> E
    E -->|HTTP| F[Qdrant Server]
    A -->|并行调用| G[gRPC stub]
    G --> F
```

资料来源：[qdrant_client/http/api/collections_api.py:1-1]()、[qdrant_client/http/api/points_api.py:1-1]()

## 身份验证与安全

### API Key 认证

远程模式下，可在 `QdrantClient` 构造时传入 `api_key` 参数，库内部将其注入到 HTTP 请求头（通常为 `api-key`）与 gRPC metadata 中，使客户端在对接启用了静态密钥的 Qdrant 服务时无需改动业务调用代码。

### TLS / SSL 加密

`QdrantClient` 同时接受 `https://` 形式的 URL，以及显式的 TLS 配置参数（如 `verify`、CA bundle 等）。社区中常见的 SSL 握手失败（issue #770，`SSL_ERROR_SSL: WRONG_VERSION_NUMBER`）多源自以下原因：客户端连接的是 HTTPS 端口但服务端未启用 TLS，或反之；客户端与服务器端 gRPC 的 TLS 配置不匹配。修复时请先确认 Qdrant 服务端的监听协议与端口，再核对客户端 URL 的 scheme。

资料来源：[qdrant_client/http/configuration.py:1-1]()、[qdrant_client/qdrant_remote.py:1-1]()

### 自定义请求头

v1.18.0 新增了"按请求自定义请求头（per-request custom headers）"能力（issue #1173），便于在分布式追踪或多租户网关中传递 traceparent、租户标识等元数据。

资料来源：[qdrant_client/http/api/points_api.py:1-1]()

## 常见故障与排错

| 故障现象 | 可能原因 | 处置建议 |
| --- | --- | --- |
| `ResponseHandlingException: The read operation timed out`（issue #380） | 网络抖动、服务端过载或客户端 `timeout` 偏小 | 调大单次调用的 `timeout`；检查服务端健康状态；升级到最新客户端版本 |
| `SSL_ERROR_SSL: WRONG_VERSION_NUMBER`（issue #770） | 协议/端口与 TLS 不匹配 | 校对 URL scheme 与服务端端口；确保两端 TLS 开关一致 |
| `SyntaxWarning: invalid escape sequence`（issue #983） | 模型描述字符串中含 `\&` 等转义 | 升级到已修复的版本；或在本地临时以 `r"..."` 抑制 |
| `upload_collection` 静默成功但数据丢失（issue #17） | 上传向量维度与 collection `vector_size` 不一致 | 上传前显式校验向量维度，或在 collection 层强制 strict mode |

资料来源：[qdrant_client/http/api_client.py:1-1]()、[qdrant_client/http/api/collections_api.py:1-1]()

## See Also

- [Qdrant Client 入门指南](https://qdrant.tech/documentation/quickstart/)
- [本地模式 vs 远程模式对比](https://qdrant.tech/documentation/guides/installation/)
- [gRPC 接口参考](https://qdrant.tech/documentation/api_reference/grpc/)
- [API 密钥与 TLS 配置](https://qdrant.tech/documentation/guides/security/)

---

<a id='page-3'></a>

## Data Operations, Uploaders & Type Conversions

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [Inference API, FastEmbed & Troubleshooting](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [qdrant_client/http/models/models.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/models/models.py)
- [qdrant_client/http/api/collections_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py)
- [qdrant_client/http/api/points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py)
- [qdrant_client/http/api/search_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/search_api.py)
- [qdrant_client/http/api/snapshots_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/snapshots_api.py)
- [qdrant_client/http/api/aliases_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/aliases_api.py)
- [qdrant_client/http/api/indexes_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/indexes_api.py)
</details>

# 数据操作、上传器与类型转换

## 概述与范围

`qdrant-client` 通过 `qdrant_client/http/api/` 目录下自动生成的 `*_api.py` 适配器与 Qdrant 服务端进行 REST 交互，涵盖点（points）、集合（collections）、别名（aliases）、索引（indexes）、快照（snapshots）等核心数据操作。每个适配器都接收 Pydantic 模型对象，由统一的 `jsonable_encoder` 序列化为 JSON 负载发送。资料来源：[qdrant_client/http/api/points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py)、[qdrant_client/http/api/collections_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py)

本主题范围：
- 点与集合等数据写入/管理接口
- 别名、索引、快照等元数据接口
- 模型层 Pydantic 类型与序列化转换机制
- 社区中常见的同步/异步、超时、SSL 与校验相关问题

## 核心数据操作接口

### 集合操作

`_CollectionsApi._build_for_collection_exists` 通过 `GET /collections/{collection_name}/exists` 判断集合是否存在，响应被反序列化为 `m.InlineResponse2008`。`_build_for_create_collection` 通过 `PUT /collections/{collection_name}` 创建集合，使用 `m.CreateCollection` 作为请求体，并通过查询参数 `timeout` 透传超时设置。资料来源：[qdrant_client/http/api/collections_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py)

### 点操作与批量上传

`_PointsApi._build_for_batch_update` 通过 `POST /collections/{collection_name}/points/batch` 提交 `m.UpdateOperations` 序列，支持 `wait`、`ordering`、`timeout` 三个查询参数；请求头自动设置为 `application/json`，负载由 `jsonable_encoder(update_operations)` 序列化。资料来源：[qdrant_client/http/api/points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py)

`_build_for_clear_payload` 等端点允许对指定集合的 payload 进行清理，是写入侧常见操作。资料来源：[qdrant_client/http/api/points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py)

### 别名、索引与快照

- **别名**：通过 `GET /aliases`、`PUT /aliases` 等端点实现集合别名的查询与更新，使用 `m.ChangeAliasesOperation` 作为请求体。资料来源：[qdrant_client/http/api/aliases_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/aliases_api.py)
- **索引**：`_IndexesApi._build_for_create_field_index` 通过 `PUT /collections/{collection_name}/index` 创建字段索引，支持 `wait`、`ordering`、`timeout` 三类参数。资料来源：[qdrant_client/http/api/indexes_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/indexes_api.py)
- **快照**：`qdrant_client/http/api/snapshots_api.py` 提供快照创建与恢复接口，便于数据迁移或备份。资料来源：[qdrant_client/http/api/snapshots_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/snapshots_api.py)

## 类型转换与序列化机制

所有 API 子模块共用同一套序列化辅助函数，定义于每个 `*_api.py` 文件顶部：

```python
def to_json(model: BaseModel, *args, **kwargs):
    if PYDANTIC_V2:
        return model.model_dump_json(*args, **kwargs)
    else:
        return model.json(*args, **kwargs)
```

`jsonable_encoder` 默认 `by_alias=True`，自动剔除 `exclude_unset` 与 `exclude_none` 字段以减少冗余负载，最终调用 `to_json` 将 Pydantic 模型序列化为 JSON 字符串再交给 `api_client.request` 发送。资料来源：[qdrant_client/http/api/points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py)、[qdrant_client/http/api/collections_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py)

模型层 `qdrant_client/http/models/models.py` 定义了大量 Pydantic 模型，下表列出与数据操作紧密相关的几个：

| 模型 | 用途 | 关键字段 |
|---|---|---|
| `Prefetch` | 子请求预取，组合查询 | `query`, `using`, `filter`, `params`, `limit` |
| `PointGroup` | 分组聚合结果 | `hits`, `id`, `lookup` |
| `PointIdsList` | 点 ID 列表选择器 | `points`, `shard_key` |
| `PeerInfo` / `PeerMetadata` | 集群节点信息 | `uri`, `version` |
| `PayloadStorageTypeOneOf` | Payload 存储类型 | `type: Literal["mmap"]` |

资料来源：[qdrant_client/http/models/models.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/models/models.py)

部分模型（如 `Prefetch`、`MinShould`）通过 `extra="forbid"` 拒绝多余字段，确保上传过程中的数据契约严格；`IndexesOneOf`、`IndexesOneOf1` 等使用 `Literal` 约束枚举值，提升类型安全。

## 常见问题与故障模式

根据社区反馈，数据操作与上传过程中常见故障包括：

```mermaid
flowchart LR
    A[客户端调用] --> B{类型与维度校验}
    B -- 失败 --> X[静默写入/异常]
    B -- 通过 --> C[jsonable_encoder 序列化]
    C --> D[HTTP/gRPC 请求]
    D --> E{网络可达?}
    E -- 否 --> Y[SSL错误/超时]
    E -- 是 --> F[服务端处理]
    F --> G[返回结果]
```

- **逃逸字符告警**：`models.py` 中部分 `description` 字段使用非原始字符串，运行时出现 `SyntaxWarning: invalid escape sequence '\&'`。资料来源：[qdrant_client/http/models/models.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/models/models.py)（社区 #983）
- **数据校验缺失**：`upload_collection` 在向量维度与目标集合不匹配时会静默成功（社区 #17），需在上层显式校验 `vector_size`。
- **读取超时**：`timeout` 过小或服务端响应慢时抛出 `ResponseHandlingException: The read operation timed out`（社区 #380），可调整查询参数 `timeout` 与重试策略缓解。
- **SSL 握手失败**：gRPC 连接出现 `WRONG_VERSION_NUMBER` 通常为协议不匹配，需正确启用 TLS（社区 #770）。
- **异步客户端**：社区长期呼吁补充 `AsyncQdrantClient` 高层封装（社区 #157），目前仍需依赖 `AsyncApiClient` 手动组装。

## See Also

- [Points API 参考](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py)
- [Collections API 参考](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py)
- [Models 模块](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/models/models.py)

---

<a id='page-4'></a>

## Inference API, FastEmbed & Troubleshooting

### 相关页面

相关主题：[Connection Modes, Transports & Authentication](#page-2), [Data Operations, Uploaders & Type Conversions](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/qdrant/qdrant-client/blob/main/README.md)
- [qdrant_client/qdrant_fastembed.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/qdrant_fastembed.py)
- [qdrant_client/async_qdrant_fastembed.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/async_qdrant_fastembed.py)
- [qdrant_client/fastembed_common.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/fastembed_common.py)
- [qdrant_client/embed/embedder.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/embed/embedder.py)
- [qdrant_client/embed/model_embedder.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/embed/model_embedder.py)
- [qdrant_client/embed/embed_inspector.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/embed/embed_inspector.py)
- [qdrant_client/http/api/points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py)
- [qdrant_client/http/api/search_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/search_api.py)
- [qdrant_client/http/api/service_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/service_api.py)
- [qdrant_client/http/models/models.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/models/models.py)
- [qdrant_client/models/__init__.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/models/__init__.py)
</details>

# Inference API、FastEmbed 与故障排查

## 概述

`qdrant-client` 提供两类推理（Inference）能力：本地推理依赖 [FastEmbed](https://github.com/qdrant/fastembed) 在 CPU/GPU 上生成向量嵌入，远端推理则可调用 Qdrant Cloud 上托管的 Inference API。本页面聚焦于本地 FastEmbed 路径，并结合社区高频问题给出常见故障排查指引。

资料来源：[README.md:1-50]()

---

## 2. 本地推理：FastEmbed 集成

### 安装与基础用法

通过可选依赖 `qdrant-client[fastembed]` 即可启用 FastEmbed 嵌入能力：

```
pip install qdrant-client[fastembed]
```

FastEmbed 基于 ONNX Runtime，可在 CPU 与 GPU 上运行。[README.md:9-50]() 给出了最小可运行示例：`QdrantClient(":memory:")` 启动本地模式，传入 `models.Document` 与模型名（如 `sentence-transformers/all-MiniLM-L6-v2`），即可在 `create_collection` 时通过 `client.get_embedding_size(model_name)` 推断向量维度，再调用 `upload_collection` 上传文本，最后用 `query_points` 执行检索。

```python
from qdrant_client import QdrantClient, models

client = QdrantClient(":memory:")
model_name = "sentence-transformers/all-MiniLM-L6-v2"

docs = [models.Document(text="Qdrant has Langchain integrations", model=model_name)]
client.create_collection(
    "demo_collection",
    vectors_config=models.VectorParams(size=client.get_embedding_size(model_name), distance=models.Distance.COSINE),
)
client.upload_collection("demo_collection", vectors=docs, ids=[42])
```

### 模块职责拆分

FastEmbed 子系统的核心文件包括同步入口 [qdrant_client/qdrant_fastembed.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/qdrant_fastembed.py) 与异步入口 [qdrant_client/async_qdrant_fastembed.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/async_qdrant_fastembed.py)；二者共享抽象定义 [qdrant_client/fastembed_common.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/fastembed_common.py)。底层嵌入逻辑由 `qdrant_client/embed/` 包实现：

| 文件 | 角色 |
| --- | --- |
| [embedder.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/embed/embedder.py) | 顶层嵌入协调器，决定走本地模型还是远端 API |
| [model_embedder.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/embed/model_embedder.py) | 加载具体模型并执行前向推理 |
| [embed_inspector.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/embed/embed_inspector.py) | 数据/向量一致性检查（参见 issue #17） |

### 数据流图

```mermaid
flowchart LR
  A[用户代码] --> B[QdrantClient / AsyncQdrantClient]
  B --> C[fastembed_common]
  C --> D[embedder.py]
  D --> E[model_embedder.py]
  E --> F[FastEmbed ONNX 模型]
  F --> E
  E --> G[向量结果]
  G --> H[upload_collection / query_points]
  H --> I[Qdrant Server HTTP/gRPC]
```

资料来源：[qdrant_client/fastembed_common.py:1-50]()、[qdrant_client/embed/embedder.py:1-30]()

---

## 3. 常见故障与排查

### 3.1 `SyntaxWarning: invalid escape sequence`

社区 issue [#983](https://github.com/qdrant/qdrant-client/issues/983) 报告在 Python 3.12+ 中加载 `qdrant_client` 会打印来自 [qdrant_client/http/models/models.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/models/models.py) 的 `SyntaxWarning`，例如 `'\&'`。解决方案是改用原始字符串 `r"..."`。在升级客户端版本前，可临时在入口文件顶部加：

```python
import warnings
warnings.filterwarnings("ignore", category=SyntaxWarning)
```

资料来源：[qdrant_client/http/models/models.py:758]()（来自 issue #983 的报错行）

### 3.2 `upload_collection` 静默写入错误维度

issue [#17](https://github.com/qdrant/qdrant-client/issues/17) 指出，当 `vector_size=256` 的数据被上传到维度为 512 的集合时，方法不会报错。客户端 `embedder.py` 与 `embed_inspector.py` 负责一致性检查；建议在调用 `upload_collection` 前显式校验维度，参考 [embed_inspector.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/embed/embed_inspector.py) 提供的检查工具，并在 `create_collection` 时使用 `client.get_embedding_size(model_name)`。

资料来源：[qdrant_client/embed/embed_inspector.py:1-30]()、issue #17

### 3.3 `ResponseHandlingException: The read operation timed out`

issue [#380](https://github.com/qdrant/qdrant-client/issues/380) 中用户从 1.3.1 升至 1.6.9 仍遇到读超时。排查方向：

1. 升级到最新版本（当前 v1.18.0）以获取 gRPC/HTTP 客户端改进。
2. 适当增大 `QdrantClient` 构造时的 `timeout` 参数。
3. 检查服务端日志与集群分片状态（见 [distributed_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/distributed_api.py) 提供的 `cluster_status`、`collection_cluster_info`）。
4. 验证服务端是否健康：[service_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/service_api.py) 提供 `/healthz`、`/livez`。

### 3.4 `SSL handshake failed`（错误码 `WRONG_VERSION_NUMBER`）

issue [#770](https://github.com/qdrant/qdrant-client/issues/770) 报告 gRPC 通道握手失败。常见原因是客户端使用了 HTTPS/443 端口连接到明文 gRPC 服务，或反之。检查点：

- `QdrantClient` 的 `url` 协议头（`https://` 对应 TLS gRPC）。
- Qdrant 服务端 `ServiceConfig` 的 gRPC 端口是否启用 TLS。
- 通过 [service_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/service_api.py) 的 `_build_for_healthz` 先确认 HTTP 健康检查可用。

### 3.5 异步客户端使用

issue [#157](https://github.com/qdrant/qdrant-client/issues/157) 讨论 `AsyncQdrantClient` 是否提供与同步同等的体验。在 FastEmbed 场景下，异步入口 [async_qdrant_fastembed.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/async_qdrant_fastembed.py) 与 [points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py) 中 `AsyncPointsApi`（含 `Async*` 方法）协同工作，可在 `asyncio` 程序中完成 upsert 与 query。

---

## 4. 最佳实践与版本要点

- **使用 `get_embedding_size`** 代替硬编码向量维度，避免与 issue #17 类似的静默错误。
- **启用 FastEmbed 时显式传入模型名**，以保证 `Document` 对象在批处理中能命中同一模型缓存。
- **为每个请求加 trace header**：v1.18.0（PR [#1173](https://github.com/qdrant/qdrant-client/pull/1173)）新增了“per request custom headers for tracing”，结合 HTTP API 中的 `headers={}` 参数可传递链路追踪信息，参见 [search_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/search_api.py) 中 `_build_for_*` 方法。
- **新集合 API**：v1.18.0 引入创建/删除命名向量 API（PR #1201），使用 [collections_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/collections_api.py) 与 [points_api.py](https://github.com/qdrant/qdrant-client/blob/main/qdrant_client/http/api/points_api.py) 中 `_build_for_update_vectors` 等方法可对已存在集合追加 named vector。

资料来源：[README.md:1-50]()、v1.18.0 发布说明

---

## 参见

- [Qdrant 官方文档：Inference API](https://qdrant.tech/documentation/inference/)
- [FastEmbed 项目主页](https://github.com/qdrant/fastembed)
- 相关 Wiki：集合与索引管理（Collections & Indexes API）、异步客户端（AsyncQdrantClient）、本地模式（Local Mode）

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：qdrant/qdrant-client

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Qdrant client causes Pydantic validation error if `QDRANT__SERVICE__HARDWARE_REPORTING=true` is passed。

## 1. 安装坑 · 来源证据：Qdrant client causes Pydantic validation error if `QDRANT__SERVICE__HARDWARE_REPORTING=true` is passed

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Qdrant client causes Pydantic validation error if `QDRANT__SERVICE__HARDWARE_REPORTING=true` is passed
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/qdrant/qdrant-client/issues/935 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/qdrant/qdrant-client | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/qdrant/qdrant-client | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/qdrant/qdrant-client | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/qdrant/qdrant-client | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/qdrant/qdrant-client | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/qdrant/qdrant-client | release_recency=unknown

<!-- canonical_name: qdrant/qdrant-client; human_manual_source: deepwiki_human_wiki -->