jinaai/jina

cloud-native-neural-search 中文技术文档

镜像概述和主要用途

cloud-native-neural-search 是一款云原生神经搜索框架镜像，专为处理任意类型数据的语义检索场景设计。该镜像基于容器化架构，集成深度学习模型与向量搜索引擎，支持从非结构化数据（文本、图像、音频）到结构化数据的统一索引与检索，适用于构建高性能、智能化的搜索与推荐系统。

核心功能和特性

云原生架构

• 容器化部署：基于OCI标准镜像，支持Docker/Kubernetes环境无缝集成
• 弹性扩展：自动扩缩容能力，适配流量波动（需结合K8s HPA或云平台弹性服务）
• 分布式架构：支持多节点集群部署，数据分片与副本机制保障高可用

神经搜索引擎

• 向量检索核心：基于深度学习模型将数据转换为向量，通过余弦相似度、欧氏距离等算法实现语义匹配
• 多模型支持：内置常见预训练模型（如BERT、ResNet、CLIP），同时支持自定义模型接入（ONNX/TensorFlow格式）
• 实时索引更新：支持数据插入/删除的近实时索引同步，延迟低至毫秒级

多模态数据兼容性

• 全类型数据支持：文本（中文/英文/多语言）、图像（JPG/PNG/视频帧）、音频（WAV/MP3）、结构化数据（JSON/CSV/数据库表）
• 数据预处理自动化：内置数据清洗、特征提取流水线，减少人工干预

高性能与可配置性

• 低延迟检索：优化的向量索引结构（如HNSW、IVF），单节点支持每秒10万+查询
• 灵活配置：支持索引参数（维度、距离度量）、模型参数（批处理大小、推理设备）、缓存策略自定义

使用场景和适用范围

电商与零售

• 商品智能搜索（基于用户 query 语义而非关键词匹配）
• 相似商品推荐（如“找相似款式”功能）

内容平台

• 视频/文章推荐系统（基于用户行为语义分析）
• 版权检测（图像/音频重复内容识别）

企业服务

• 知识库检索（文档/邮件/聊天记录的语义问答）
• 内部数据资产管理（多源数据统一检索入口）

科研与AI应用

• 生物信息学（蛋白质序列相似性检索）
• 计算机视觉（图像检索、目标检测结果过滤）

使用方法和配置说明

前提条件

• Docker 20.10+ 或 Kubernetes 1.21+ 环境
• 单节点部署：至少 4GB 内存、2核CPU；集群部署需额外配置共享存储（如NFS/Ceph）

获取镜像

bash
# 从Docker Hub拉取（假设官方镜像名）
docker pull docker.xuanyuan.run/cloudnative/neural-search:latest

# 或从私有仓库拉取（需替换仓库地址）
docker pull registry.example.com/cloud-native-neural-search:v1.2.0

快速启动（docker run）

基础启动命令

bash
docker run -d \
  --name neural-search \
  -p 8080:8080 \  # 服务端口映射
  -v /data/neural-search:/app/data \  # 持久化数据目录（索引/模型缓存）
  -e LOG_LEVEL=info \  # 日志级别：debug/info/warn/error
  -e MODEL_NAME=bert-base-uncased \  # 默认文本编码器模型
  cloudnative/neural-search:latest

自定义模型与索引配置

bash
docker run -d \
  --name neural-search-custom \
  -p 8080:8080 \
  -v /local/models:/app/custom-models \  # 挂载本地自定义模型
  -v /data/neural-search:/app/data \
  -e PORT=8080 \
  -e MODEL_PATH=/app/custom-models/my-clip-model \  # 指定自定义模型路径
  -e INDEX_DIM=512 \  # 向量维度（需与模型输出匹配）
  -e DISTANCE_METRIC=cosine \  # 距离度量：cosine/euclidean/dot
  cloudnative/neural-search:latest

Docker Compose 部署

适用于开发/测试环境，集成依赖服务（如Redis缓存、Prometheus监控）：

yaml
# docker-compose.yml
version: "3.8"
services:
  neural-search:
    image: docker.xuanyuan.run/cloudnative/neural-search:latest
    container_name: neural-search
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - ./custom-models:/app/custom-models
    environment:
      - PORT=8080
      - LOG_LEVEL=info
      - MODEL_PATH=/app/custom-models/clip-vit-base-patch32
      - INDEX_DIM=512
      - DISTANCE_METRIC=cosine
      - REDIS_URL=redis://redis:6379  # 缓存服务地址
    depends_on:
      - redis

  redis:
    image: docker.xuanyuan.run/redis:7.0-alpine
    container_name: neural-search-redis
    volumes:
      - ./redis-data:/data
    ports:
      - "6379:6379"

启动命令：docker-compose up -d

配置参数说明

环境变量配置

基本使用流程

1. 启动服务

通过上述docker run或docker-compose命令启动服务，检查状态：

bash
# 查看容器日志
docker logs -f neural-search

# 验证服务健康状态（返回200 OK表示启动成功）
curl http://localhost:8080/health

2. 创建索引

通过API创建数据索引（以文本数据为例）：

bash
curl -X POST http://localhost:8080/indexes \
  -H "Content-Type: application/json" \
  -d '{
    "index_name": "product_catalog",
    "data_type": "text",
    "dim": 768,  # 需与模型输出维度一致
    "distance_metric": "cosine"
  }'

3. 插入数据

向索引中插入文本数据（自动转换为向量）：

bash
curl -X POST http://localhost:8080/indexes/product_catalog/insert \
  -H "Content-Type: application/json" \
  -d '{
    "id": "prod_123",
    "content": "无线蓝牙耳机 主动降噪 续航30小时",
    "metadata": {"price": 299, "brand": "Example"}  # 附加结构化元数据（可选）
  }'

4. 执行检索

基于语义查询相似数据：

bash
curl -X GET "http://localhost:8080/indexes/product_catalog/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "降噪耳机 长续航",
    "top_k": 5  # 返回Top 5相似结果
  }'

注意事项

• 模型选择：图像/音频数据需使用对应模态模型（如CLIP、VGG），维度需与索引配置匹配，否则会导致插入失败
• 性能调优：高并发场景建议开启Redis缓存（REDIS_URL），并调整CACHE_SIZE至物理内存30%~50%
• 数据持久化：生产环境需将/app/data目录挂载至持久化存储，避免容器重启后索引丢失