数据分析agent 四：docker qdrant 镜像拉取，和教程

# 一 ：Qdrant 镜像拉取

### docker pull qdrant/qdrant

### docker load -i E:/笔记2026项目/项目一_问数/1.docker镜像/qdrant.tar

### docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

### 参数说明：
    docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant

    -d：后台运行容器
    
    --name qdrant：指定容器名称
    
    -p 6333:6333：映射 HTTP API 端口
    
    -p 6334:6334：映射 gRPC API 端口

### http://localhost:6333/dashboard


# ==========================================================================

# 二. 数据持久化启动（推荐）
    ⚠️ Windows 特别注意：官方文档提示，在 Windows 上直接挂载本地文件夹可能存在兼容性问题，建议使用 Docker 命名卷（volume） 替代文件夹挂载。
    
    推荐方式：使用 Docker 卷
    
    bash
    docker run -d \
      --name qdrant \
      -p 6333:6333 \
      -p 6334:6334 \
      -v qdrant_data:/qdrant/storage \
      qdrant/qdrant
    这样数据会保存在 Docker 管理的卷中，稳定可靠，不会因 Windows 文件系统兼容性问题导致数据损坏。

### 备选方式：挂载本地文件夹（如遇问题可切换为卷方式）

    bash
    docker run -d \
      --name qdrant \
      -p 6333:6333 \
      -p 6334:6334 \
      -v "$(pwd)/qdrant_storage:/qdrant/storage" \
      qdrant/qdrant
    注意 $(pwd) 在 PowerShell 中有效，CMD 用户需替换为完整路径。

# 三. 生产环境启动（带资源限制和 API 密钥）
    bash
    docker run -d \
      --name qdrant \
      -p 6333:6333 \
      -p 6334:6334 \
      -v qdrant_data:/qdrant/storage \
      -e QDRANT__SERVICE__API_KEY=your_secure_api_key \
      --restart unless-stopped \
      --memory 4g \
      --cpus 2 \
      qdrant/qdrant
    额外参数说明：
    
    -e QDRANT__SERVICE__API_KEY：设置 API 访问密钥，增强安全性
    
    --restart unless-stopped：容器异常退出时自动重启
    
    --memory 和 --cpus：限制资源使用

    # 四、验证部署
    启动成功后，可以通过以下方式验证：
    
    访问 Web UI：浏览器打开 http://localhost:6333/dashboard
    
    查看 API 状态：访问 http://localhost:6333 查看服务信息
    
    查看容器日志：
    
    bash
    docker logs qdrant
    五、容器管理常用命令
    操作  命令
    查看运行状态  docker ps
    停止容器    docker stop qdrant
    启动已存在容器 docker start qdrant
    删除容器    docker rm -f qdrant
    查看日志    docker logs qdrant



# ====================================================================================

Python 连接 Qdrant 验证代码
下面提供一套完整的 Python 代码，用于验证 Qdrant 是否部署成功，并演示基本的向量存储和搜索操作。

# 一、安装 Python 依赖
    bash
    pip install qdrant-client numpy
# 二、基础验证代码（测试连接）

from qdrant_client import QdrantClient
from qdrant_client.http import models

# 1. 连接 Qdrant（默认本地部署）
client = QdrantClient(host="localhost", port=6333)
try:
    # 获取 collections 列表，能正常返回说明连接成功
    collections = client.get_collections()
    print("✅ Qdrant 连接成功！")
    print(f"📊 当前存在的 Collection 数量: {len(collections.collections)}")
    for col in collections.collections:
        print(f"   - {col.name}")
except Exception as e:
    print(f"❌ 连接失败: {e}")

 

# 2. 查看服务健康状态


# 三、完整功能验证（创建 Collection + 插入向量 + 搜索）

from qdrant_client import QdrantClient
from qdrant_client.http import models
import numpy as np

# 连接 Qdrant
client = QdrantClient(host="localhost", port=6333)

COLLECTION_NAME = "test_demo"

# 1. 删除已存在的同名 Collection（清理测试环境）
if client.collection_exists(COLLECTION_NAME):
    client.delete_collection(COLLECTION_NAME)
    print(f"🗑️ 已删除旧 Collection: {COLLECTION_NAME}")

# 2. 创建 Collection
client.create_collection(
    collection_name=COLLECTION_NAME,
    vectors_config=models.VectorParams(
        size=4,              # 向量维度 = 4
        distance=models.Distance.COSINE  # 相似度度量方式
    )
)
print(f"✅ Collection 创建成功: {COLLECTION_NAME}")

# 3. 准备测试数据（4 维向量 + 对应的 payload 元数据）
points = [
    models.PointStruct(
        id=1,
        vector=[0.1, 0.2, 0.3, 0.4],
        payload={"name": "item_a", "category": "fruit"}
    ),
    models.PointStruct(
        id=2,
        vector=[0.5, 0.6, 0.7, 0.8],
        payload={"name": "item_b", "category": "fruit"}
    ),
    models.PointStruct(
        id=3,
        vector=[0.9, 1.0, 1.1, 1.2],
        payload={"name": "item_c", "category": "vegetable"}
    ),
    models.PointStruct(
        id=4,
        vector=[2.0, 1.8, 1.6, 1.4],
        payload={"name": "item_d", "category": "vegetable"}
    ),
]

# 4. 插入数据
client.upsert(
    collection_name=COLLECTION_NAME,
    points=points
)
print(f"📥 已插入 {len(points)} 条数据")

# 5. 执行向量搜索（新版本 API）
query_vector = [0.15, 0.25, 0.35, 0.45]

# ✅ 修改点：使用 query_points 替代 search
search_result = client.query_points(
    collection_name=COLLECTION_NAME,
    query=query_vector,  # 注意参数名从 query_vector 改为 query
    limit=3,
    with_payload=True
)

print(f"\n🔍 搜索向量: {query_vector}")
print("最相似的结果（按相似度降序）:")
# ✅ 修改点：结果在 search_result.points 中
for idx, result in enumerate(search_result.points, 1):
    print(f"  {idx}. ID={result.id}, 相似度={result.score:.4f}")
    print(f"     元数据: {result.payload}")

 

## 四、执行结果示例
运行成功后，你会在终端看到类似以下输出：

```text

✅ Qdrant 连接成功！
📊 当前存在的 Collection 数量: 0

🗑️ 已删除旧 Collection: test_demo
✅ Collection 创建成功: test_demo
📥 已插入 4 条数据

🔍 搜索向量: [0.15, 0.25, 0.35, 0.45]
最相似的结果（按相似度降序）:
  1. ID=1, 相似度=0.9999
     元数据: {'name': 'item_a', 'category': 'fruit'}
  2. ID=2, 相似度=0.9565
     元数据: {'name': 'item_b', 'category': 'fruit'}
  3. ID=3, 相似度=0.8930
     元数据: {'name': 'item_c', 'category': 'vegetable'}
```
 

# 五、带 API 密钥的连接方式
如果你在启动 Qdrant 时设置了 API_KEY：

from qdrant_client import QdrantClient

client = QdrantClient(
    host="localhost",
    port=6333,
    api_key="your_secure_api_key"  # 与 docker run 时设置的 API_KEY 一致
)

 
# 六、高级验证：指定 Collection 的 JSON 导入/导出
1. 从 JSON 文件导入数据

import json
from qdrant_client import QdrantClient
from qdrant_client.http import models

client = QdrantClient(host="localhost", port=6333)

with open("vectors.json", "r", encoding="utf-8") as f:
    data = json.load(f)  # 格式: [{"id": 1, "vector": [...], "payload": {...}}]

client.upsert(
    collection_name="your_collection",
    points=[
        models.PointStruct(
            id=item["id"],
            vector=item["vector"],
            payload=item.get("payload", {})
        )
        for item in data
    ]
)

 
#### 2. 导出 Collection 全部数据

scroll_result = client.scroll(
    collection_name="your_collection",
    limit=100,  # 每次最多 100 条
    with_payload=True,
    with_vectors=True
)

for point in scroll_result[0]:
    print(f"ID: {point.id}, Vector: {point.vector}, Payload: {point.payload}")

# 七、常见问题
    连接超时或拒绝连接
    
    检查 Qdrant 容器是否正常运行：docker ps | findstr qdrant
    
    检查防火墙是否放行 6333 端口
    
    Collection 创建失败
    
    Qdrant 1.7.0 以下版本不支持某些参数，可尝试升级镜像版本
    
    检查向量维度与实际数据是否一致


# ==================================

# 1. 官方 Web UI (最直接)
# 在你启动 Qdrant 容器后，打开电脑上的浏览器，在地址栏输入以下地址即可访问 Web UI 管理界面：

#  http://localhost:6333/dashboard

    这个界面非常直观，你可以在这里完成很多管理操作：
    
    控制台 (Console)：可以直接在网页上调用 Qdrant 的 REST API，非常适合调试和测试。
    
    集合 (Collections)：查看、创建和管理你的所有集合，也可以上传快照。
    
    教程 (Tutorial)：官方提供了一套交互式教程，可以跟着示例数据上手学习。
    
    监控仪表盘：在 Qdrant Cloud 的集群概览页面，你还可以看到节点、CPU、内存等资源的使用情况可视化图表。