# feature_client

**Repository Path**: pet_520/feature_client

## Basic Information

- **Project Name**: feature_client
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-11
- **Last Updated**: 2026-01-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# siglip2 — 猫狗匹配与检索

一个基于 SigLIP2 的宠物图像检索/匹配项目：通过 API 接口提取特征，特征统一上传到阿里云 OSS；匹配脚本输入特征后在 OSS 中进行检索/比对。支持普通 OSS 特征存储和向量 OSS 向量检索。接口地址与 OSS 配置集中在 `config/config.yaml`。

## 核心功能

- 特征提取：通过 API 接口提取宠物图像特征，支持多图池化与分支融合
- 特征存储：特征文件上传到阿里云普通 OSS，作为统一特征库
- 向量存储：特征向量同步到阿里云向量 OSS，支持高效向量检索
- 特征匹配：支持普通 OSS JSON 扫描匹配与向量 OSS 向量索引检索
- 配置集中：API 地址与 OSS 参数均在 `config/config.yaml` 统一配置

## 改造后的数据流

1. 调用 API 提取图像特征（global/face/local/text）。
2. 将特征序列化并上传至 OSS（按数据集/宠物 ID 组织 Key）。
3. 匹配脚本读取输入特征，在 OSS 中拉取特征库并完成 Top-K 匹配。

## 目录结构（改造后重点变化）

```
.
├─ config/                                   # 配置文件目录
│  └─ config.yaml                            # 示例配置文件
├─ src/
│  ├─ config/                                # 配置管理
│  │  └─ __init__.py                         # 支持 YAML 配置和环境变量
│  └─ utils/                                 # 工具函数
├─ scripts/
│  ├─ upload_features_oss.py                 # 提取特征并上传 OSS（新增）
│  ├─ match_oss_features.py                  # 输入特征后在 OSS 中匹配（新增）
│  ├─ local_match_by_id.py                   # 按 ID 在 OSS/向量索引中匹配（新增）
│  └─ bench_api_single.py                    # API 单条请求耗时测试
└─ requirements.txt                          # 项目依赖
```

## 安装与配置

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置

请在 `config/config.yaml` 中配置 API 地址与 OSS 访问参数：

#### 2.1 API 配置
```yaml
api:
  local_url: http://180.97.221.107:8030  # 本地测试 API 的基础 URL
```

#### 2.2 普通 OSS 配置（用于特征存储）
```yaml
oss:
  normal:
    endpoint: oss-cn-beijing.aliyuncs.com  # 普通 OSS Endpoint
    bucket: pethome9527                    # 普通 Bucket
    region: "cn-beijing"                   # 地区
  access_key_id: "LTAI5tSks3rTMdqH1L1mf71r"        # 阿里云 Access Key ID
  access_key_secret: "E2VTSYhxBfeASEytKib3VkyO6H5IF4"  # 阿里云 Access Key Secret
  prefix: features                        # 特征存储前缀
```

#### 2.3 向量 OSS 配置（用于高效向量检索）
```yaml
oss:
  vector:
    endpoint: cn-hangzhou.oss-vectors.aliyuncs.com   # 向量 OSS Endpoint
    bucket: petfeature                               # 向量 Bucket
    region: "cn-hangzhou"                            # 必须显式指定 region
    account_id: "1803617703889960"                   # 必填，用于向量操作
    vector_indexes:                                  # 按特征分支绑定向量索引名
      global: "global"
      face: "face"
      local: "local"
      text: "text"
```

**注意**：向量 OSS 配置是可选的，仅在需要使用向量索引检索时配置。

## 快速开始

### 1. 提取特征并上传 OSS

```bash
# 处理单个宠物ID
python scripts/upload_features_oss.py --pet_id 123

# 指定图片来源为OSS
python scripts/upload_features_oss.py --pet_id 123 --image-source "oss"

# 指定发布类型
python scripts/upload_features_oss.py --pet_id 123 --publish "publish"
```
 
常用参数：
- `--pet_id`：宠物ID（必填）。
- `--image-source`：图片获取来源，可选项：`database`（默认，从数据库img_list获取）或 `oss`（通过ID在OSS上查找）。
- `--publish`：发布类型，可选项：`publish` 或 `search`。


### 2. 输入特征并在 OSS 中匹配

```bash
python scripts/match_oss_features.py --feature-json "path/to/feature.json" --top-k 10
python scripts/match_oss_features.py --query data/queries/my_dog --top-k 10 --local
```

说明：
- `--feature-json`：直接输入已保存的特征文件。
- `--query`：输入查询图片目录，脚本会先调用 API 提取特征，再在 OSS 中匹配。
- 默认优先使用向量索引（`oss.vector_index` 已配置时）；加 `--use-oss-scan` 可强制改为 OSS JSON 扫描。

### 3. 按 ID 匹配（本地可视化）

```bash
python scripts/local_match_by_id.py --id <pet_id> --feature-type global --top-k 10
```

说明：
- 默认优先使用向量索引；加 `--use-oss-scan` 可强制改为 OSS JSON 扫描。
- 加 `--use-vectors-api` 可使用 `ossutil vectors-api`。

## 完整工作流程

### 1. 图像准备

**输入要求**：
- 支持的图像格式：JPG、PNG、BMP、WebP
- 单张图像大小建议不超过 10MB
- 多图输入时，建议控制在 5 张以内，避免 API 超时

**可选：添加描述文本**：
在图像目录下创建 `desc.json` 文件，为图像添加文本描述：
```json
{
  "desc": "这是一只金毛犬，毛发金黄色，正在草地上玩耍"
}
```

### 2. 特征提取与上传

#### 2.1 上传特征（从数据库）

使用 `upload_features_oss.py` 脚本从数据库获取数据并上传特征：

```bash
# 基本用法
python scripts/upload_features_oss.py --pet_id 123

# 指定 bucket
python scripts/upload_features_oss.py --pet_id 123 --bucket "my-bucket"

# 指定发布类型
python scripts/upload_features_oss.py --pet_id 123 --publish "publish"

# 指定图片获取来源
python scripts/upload_features_oss.py --pet_id 123 --image-source "oss"
```

**参数说明**：
- `--pet_id`：宠物 ID（必填，整数）
- `--bucket`：OSS bucket 名称（可选，默认从配置文件获取）
- `--publish`：发布类型，可选值：publish 或 search，默认为 None
- `--image-source`：图片获取来源，可选值：database（默认，从数据库img_list获取）或 oss（通过ID在OSS上查找）

#### 2.2 同步数据库特征

使用 `sync_from_database.py` 脚本从数据库同步特征到向量 OSS：

```bash
# 限制同步数量
python scripts/sync_from_database.py --limit 100

# 同步单个 ID
python scripts/sync_from_database.py --id 123
```

**参数说明**：
- `--id`：指定单个 ID 进行同步（可选）
- `--limit`：限制同步的记录数量（可选）
- `--start-id`：从指定 ID 开始同步（可选）

### 3. 特征查询与匹配

#### 3.1 基于图像查询

使用 `match_oss_features.py` 脚本输入图像目录，自动提取特征并查询：

```bash
# 从本地 API 提取特征并查询
python scripts/match_oss_features.py --query "path/to/images" --top-k 10 --local

# 使用特定特征分支
python scripts/match_oss_features.py --query "path/to/images" --top-k 10 --branches "glf" --local
```

#### 3.2 基于特征文件查询

直接使用已保存的特征文件进行查询：

```bash
python scripts/match_oss_features.py --feature-json "path/to/feature.json" --top-k 10
```

#### 3. 基于 ID 的加权匹配

使用 `find_similar_with_weights.py` 脚本根据输入 ID 和权重进行综合特征匹配：

```bash
# 使用默认权重（global:0.4, local:0.2, face:0.3, text:0.1）
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10

# 指定自定义权重
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10 --weights "0.5,0.1,0.3,0.1"

# 指定搜索类型（publish 或 search）
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10 --search "publish"

# 使用类别过滤（自动获取输入ID的类别，只返回同类别结果）
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10 --filter-category --category-source "metadata" --category-field "pet_type"

# 使用状态过滤
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10 --status "丢失"
```

**参数说明**：
- `--id`：输入的 pet_id（必填）
- `--top-k`：返回的相似结果数量（默认：10）
- `--weights`：特征权重，格式为 "global,local,face,text"（默认：0.4,0.2,0.3,0.1）
- `--bucket`：OSS bucket 名称（可选，默认从配置文件获取）
- `--search`：搜索类型，可选值：publish、search 或 None（默认：None）
- `--filter-category`：是否按类别过滤结果，启用后自动获取输入ID的类别并只返回同类别结果（可选）
- `--category-source`：类别来源，可选值：metadata 或 mysql（默认：metadata）
- `--category-field`：类别字段名（默认：pet_type）
- `--status`：要过滤的状态值（可选）

### 4. 结果分析

查询结果将显示：
- 排名（Rank）
- 相似度分数/距离（Score/Distance）
- 宠物 ID（Pet ID）
- 元数据（Metadata）

示例输出：
```
Rank 01: distance=0.123456 id=pet456 metadata={'name': '小白', 'breed': '金毛', 'gender': '公'}
Rank 02: distance=0.234567 id=pet789 metadata={'name': '小黑', 'breed': '拉布拉多', 'gender': '母'}
```

## 脚本使用方法详解

### 1. upload_features_oss.py

**功能**：从数据库获取宠物信息，提取特征并上传到阿里云向量 OSS，支持多种特征分支。

**使用示例**：
```bash
# 基本用法
python scripts/upload_features_oss.py --pet_id 123

# 指定 bucket
python scripts/upload_features_oss.py --pet_id 123 --bucket "my-bucket"

# 指定发布类型
python scripts/upload_features_oss.py --pet_id 123 --publish "publish"

# 指定图片获取来源
python scripts/upload_features_oss.py --pet_id 123 --image-source "oss"
```

**参数说明**：
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| --pet_id | integer | 是 | 宠物 ID |
| --bucket | string | 否 | OSS bucket 名称，默认从配置文件获取 |
| --publish | string | 否 | 发布类型：publish 或 search，默认为 None |
| --image-source | string | 否 | 图片获取来源：database（默认，从数据库img_list获取）或 oss（通过ID在OSS上查找） |

### 2. match_oss_features.py

**功能**：输入特征或查询图像，在 OSS 中进行匹配检索，支持向量索引和 OSS 扫描两种方式。

**使用示例**：
```bash
# 使用特征文件查询
python scripts/match_oss_features.py --feature-json "path/to/feature.json" --top-k 10

# 使用查询图像目录（自动提取特征）
python scripts/match_oss_features.py --query "path/to/images" --top-k 10

# 指定使用 OSS 扫描模式
python scripts/match_oss_features.py --feature-json "path/to/feature.json" --top-k 10 --use-oss-scan

# 使用本地 API 提取特征并查询
python scripts/match_oss_features.py --query "path/to/images" --top-k 10 --local
```

**参数说明**：
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| --feature-json | string | 否 | 特征文件路径（与 --query 二选一） |
| --query | string | 否 | 查询图像目录（与 --feature-json 二选一） |
| --top-k | integer | 是 | 返回的相似结果数量 |
| --use-oss-scan | flag | 否 | 强制使用 OSS JSON 扫描模式 |
| --local | flag | 否 | 使用本地 API 地址 |
| --branches | string | 否 | 特征分支选择，g/l/f/t 组合 |

### 3. find_similar_with_weights.py

**功能**：根据输入 ID 和权重对 GLFT 特征进行综合匹配，支持特征权重配置、搜索类型过滤、类别过滤和状态过滤。

**使用示例**：
```bash
# 使用默认权重
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10

# 指定自定义权重
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10 --weights "0.5,0.1,0.3,0.1"

# 指定搜索类型
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10 --search "publish"

# 指定 bucket
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10 --bucket "my-bucket"

# 使用类别过滤（自动获取输入ID的类别，只返回同类别结果）
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10 --filter-category --category-source "metadata" --category-field "pet_type"

# 使用状态过滤
python scripts/find_similar_with_weights.py --id "pet123" --top-k 10 --status "丢失"
```

**参数说明**：
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| --id | string | 是 | 输入的 pet_id |
| --top-k | integer | 否 | 返回的相似结果数量，默认 10 |
| --weights | string | 否 | 特征权重，格式为 "global,local,face,text"，默认 "0.4,0.2,0.3,0.1" |
| --bucket | string | 否 | OSS bucket 名称，默认从配置文件获取 |
| --search | string | 否 | 搜索类型，可选值：publish、search 或 None |
| --filter-category | flag | 否 | 是否按类别过滤结果，启用后自动获取输入ID的类别并只返回同类别结果 |
| --category-source | string | 否 | 类别来源，可选值：metadata 或 mysql（默认：metadata） |
| --category-field | string | 否 | 类别字段名（默认：pet_type） |
| --status | string | 否 | 要过滤的状态值 |

### 4. sync_from_database.py

**功能**：从数据库同步特征数据到阿里云向量 OSS，支持批量同步和单个 ID 同步。

**使用示例**：
```bash
# 同步所有数据
python scripts/sync_from_database.py

# 限制同步数量
python scripts/sync_from_database.py --limit 100

# 从指定 ID 开始同步
python scripts/sync_from_database.py --start-id 500

# 同步单个 ID
python scripts/sync_from_database.py --id 123

# 同步单个 ID 并指定发布类型
python scripts/sync_from_database.py --id 123 --publish "publish"

# 同步单个 ID 并指定图片来源
python scripts/sync_from_database.py --id 123 --image-source "oss"
```

**参数说明**：
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| --id | string | 否 | 指定单个帖子 ID 进行处理 |
| --limit | integer | 否 | 处理的帖子数量，默认 100 |
| --offset | integer | 否 | 偏移量，默认 0 |
| --start-id | integer | 否 | 从指定 ID 开始同步 |
| --status | string | 否 | 帖子状态 |
| --workers | integer | 否 | 并发线程数，默认 4 |
| --publish | string | 否 | 发布类型：publish 或 search，默认为 None |
| --image-source | string | 否 | 图片获取来源：database（默认，从数据库img_list获取）或 oss（通过ID在OSS上查找） |

### 5. delete_feature_vector.py

**功能**：删除指定 ID 或所有 ID 的特征向量，支持按特征类型删除和批量删除。

**使用示例**：
```bash
# 删除单个 ID 的特定特征类型向量
python scripts/delete_feature_vector.py --id "209" --feature "global"

# 删除单个 ID 的多个特征类型向量
python scripts/delete_feature_vector.py --id "209" --feature "global" "local" "face"

# 删除单个 ID 的所有特征类型向量
python scripts/delete_feature_vector.py --id "209" --all

# 删除所有 ID 的特定特征类型向量
python scripts/delete_feature_vector.py --all-ids --feature "global"

# 删除所有 ID 的多个特征类型向量
python scripts/delete_feature_vector.py --all-ids --feature "global" "local" "face"

# 删除所有 ID 的所有特征类型向量
python scripts/delete_feature_vector.py --all-ids --all

# 模拟删除操作（不实际删除）
python scripts/delete_feature_vector.py --all-ids --feature "global" --dry-run
```

**参数说明**：
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| --id | string | 否 | 要删除的宠物 ID（与 --all-ids 二选一） |
| --all-ids | flag | 否 | 删除所有 ID 的向量（与 --id 二选一） |
| --feature | string | 否 | 要删除的特征类型，可指定多个（与 --all 二选一） |
| --all | flag | 否 | 删除所有特征类型（与 --feature 二选一） |
| --bucket | string | 否 | OSS bucket 名称，默认从配置文件获取 |
| --dry-run | flag | 否 | 模拟删除操作，不实际删除向量 |

### 6. bench_api_single.py

**功能**：测试 API 单条请求的耗时，支持多次运行并计算平均值。

**使用示例**：
```bash
# 基本用法
python scripts/bench_api_single.py --image "path/to/image.jpg"

# 多次运行并计算平均值
python scripts/bench_api_single.py --image "path/to/image.jpg" --runs 5

# 使用本地 API 和会话重用
python scripts/bench_api_single.py --image "path/to/image.jpg" --local --session
```

**参数说明**：
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| --image | string | 是 | 测试图像路径 |
| --runs | integer | 否 | 运行次数，默认 1 |
| --local | flag | 否 | 使用本地 API 地址 |
| --session | flag | 否 | 重用 HTTP 会话 |

## 核心组件

### 1. 特征提取 Pipeline

`src/pipelines/feature_pipeline.py`

- 通过 HTTP API 调用提取图像特征
- 支持多图输入，输出 global/face/local/text 四路特征
- 支持文本描述融合（通过 desc.json）

### 2. OSS 匹配逻辑

`src/pipelines/match_oss.py`（新增）

- 读取输入特征或查询图像
- 从 OSS 拉取特征库（按前缀/数据集）
- 基于余弦相似度进行 Top-K 匹配（JSON 扫描模式）
  
向量索引检索使用 `src/utils/oss_vectors_client.py` 调用官方 vectors SDK。

## 配置系统

### 配置优先级

配置优先级从高到低：
1. 命令行参数
2. 环境变量
3. 本地配置文件 (local.yaml)
4. 项目配置文件 (config.yaml)
5. 默认配置文件 (default.yaml)
6. 代码默认值

### 完整配置文件结构

```yaml
# 项目信息
project:
  name: siglip2-pet-search
  version: 1.0.0

# 特征存储配置
features:
  backend: oss  # 特征存储后端：oss

# API配置
api:
  local_url: http://180.97.221.107:8030  # 本地测试 API 的基础 URL

# 信息数据库配置（MySQL）
database:
  host: "180.97.221.107"
  port: 3306
  user: "root"
  password: "AdXJPQRyZHZe6pM6KcV4"
  database: "pethome_db"
  table: "pethome_post"

# OSS 配置（阿里云）
oss:
  # 向量 OSS 配置（用于特征存储和检索）
  vector:
    endpoint: cn-hangzhou.oss-vectors.aliyuncs.com
    bucket: petfeature
    region: "cn-hangzhou"
    account_id: "1803617703889960"
    vector_indexes:
      global: "global"
      face: "face"
      local: "local"
      text: "text"
  # 普通 OSS 配置（用于图片存储）
  normal:
    endpoint: oss-cn-beijing.aliyuncs.com
    bucket: pethome9527
    region: "cn-beijing"
  # 通用配置
  access_key_id: "LTAI5tSks3rTMdqH1L1mf71r"
  access_key_secret: "E2VTSYhxBfeASEytKib3VkyO6H5IF4"
  prefix: features
  disable_env_proxy: true
```

## 代码示例
```


### 1. 使用 APIClient 提取特征

`APIClient` 是一个 HTTP 客户端，用于封装图片上传和 API 调用，支持多种特征提取接口。**注意**：`APIClient.extract` 方法返回的是特征的存在性和大小信息，而不是实际的特征向量数据。

```python
from src.utils.api_client import APIClient

# 初始化 APIClient
client = APIClient(
    local_url="http://180.97.221.107:8030",  # 可选，默认从配置文件获取
    use_local=False,  # 是否使用本地 API 地址
    use_session=True,  # 是否重用 HTTP 会话
    timeout=600.0  # 请求超时时间
)

# 提取特征（返回特征的存在性和大小信息）
data = client.extract(
    images=["path/to/image1.jpg", "path/to/image2.jpg"],  # 图片路径列表
    meta={"desc": "这是一只可爱的狗狗"},  # 元数据，会序列化为 meta_json
    extra_form={"branches": "glft"}  # 额外的表单字段
)

# 查看返回的特征信息
print("特征存在性信息:")
print(data.get("features_present", {}))
print("\n处理时间信息:")
print(data.get("timings", {}))

# 上传宠物信息
data = client.upsert(
    pet_id="pet123",  # 宠物 ID
    images=["path/to/image.jpg"],  # 图片路径列表
    desc="这是一只金毛犬",  # 文本描述
    meta={"age": 2, "breed": "Golden Retriever"}  # 元数据
)

# 直接搜索
data = client.search(
    images=["path/to/image.jpg"],  # 图片路径列表
    top_k=10,  # 返回前 10 个结果
    feature_type="fused",  # 特征类型
    meta={"return_type": "all"}  # 元数据
)

print(data)
```

### 2. 使用 OSSVectorClient 进行向量检索

`OSSVectorClient` 是一个向量索引客户端，用于调用阿里云 OSS 向量索引服务进行相似性搜索。

```python
from src.utils.oss_vectors_client import OSSVectorClient
import numpy as np

# 初始化 OSSVectorClient
vector_client = OSSVectorClient(
    endpoint="cn-hangzhou.oss-vectors.aliyuncs.com",  # 可选，默认从配置文件获取
    region="cn-hangzhou",  # 可选，默认从配置文件获取
    account_id="1803617703889960",  # 可选，默认从配置文件获取
    access_key_id="LTAI5tSks3rTMdqH1L1mf71r",  # 可选，默认从配置文件获取
    access_key_secret="E2VTSYhxBfeASEytKib3VkyO6H5IF4"  # 可选，默认从配置文件获取
)

# 准备查询向量（示例：随机生成一个 768 维的向量）
query_vector = np.random.rand(768).tolist()

# 查询相似向量
results = vector_client.query_vectors(
    bucket="petfeature",  # OSS Bucket 名称
    index_name="global",  # 向量索引名称
    vector=query_vector,  # 查询向量
    top_k=10,  # 返回前 10 个结果
    return_distance=True,  # 是否返回距离
    return_metadata=True  # 是否返回元数据
)

# 打印查询结果
for i, result in enumerate(results, 1):
    print(f"Rank {i}: distance={result.get('distance')}, id={result.get('id')}, metadata={result.get('metadata')}")

# 获取指定键的向量
keys = ["pet1", "pet2", "pet3"]
vector_data = vector_client.get_vectors(
    bucket="petfeature",  # OSS Bucket 名称
    index_name="global",  # 向量索引名称
    keys=keys,  # 向量键列表
    return_data=True,  # 是否返回向量数据
    return_metadata=True  # 是否返回元数据
)

print(vector_data)
```

### 3. Metadata 结构与作用

#### Metadata 结构

当使用 `sync_from_database.py` 脚本同步数据到向量 OSS 时，会为每个特征向量添加以下 metadata：

| 字段名 | 类型 | 说明 | 示例值 |
|-------|------|------|--------|
| post_id | 字符串 | 帖子 ID | "177" |
| pet_type | 字符串 | 宠物类型 | "狗" |
| name | 字符串 | 宠物名称 | "小白" |
| breed | 字符串 | 宠物品种 | "金毛" |
| gender | 字符串 | 宠物性别 | "公" |
| lost_location | 字符串 | 丢失地点 | "北京市朝阳区" |
| find_location | 字符串 | 发现地点 | "" |
| city | 字符串 | 城市 | "北京" |
| create_time | 字符串 | 创建时间 | "2026-01-09 10:00:00" |
| status | 字符串 | 帖子状态 | "丢失" |
| publish | 字符串 | 发布类型 | "publish" / "search" / null |

#### Metadata 作用

1. **提供上下文信息**：metadata 包含了宠物的基本信息，如品种、性别、丢失地点等，这些信息可以帮助理解搜索结果的上下文。

2. **支持过滤和排序**：在搜索结果中，可以根据 metadata 中的字段进行过滤和排序，例如只查看特定城市或特定品种的宠物。

3. **隐私保护**：metadata 中不包含联系人姓名和联系电话等隐私信息，保护了用户的隐私。

4. **发布类型管理**：通过 `publish` 字段，可以区分不同类型的发布，实现更精确的搜索匹配：
   - 当 `search_type` 是 "publish" 时，只匹配 `publish` 字段为 "search" 或 null 的结果
   - 当 `search_type` 是 "search" 时，只匹配 `publish` 字段为 "publish" 或 null 的结果
   - 当 `search_type` 是 null 时，匹配所有结果

5. **结果展示**：在搜索结果中，可以显示 metadata 中的信息，为用户提供更丰富的结果展示。

## API 使用说明（节选）

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| images | file | 是 | 图像文件，支持多个 |
| return_type | string | 否 | 返回类型，默认 "all" |
| desc | string | 否 | 图像描述文本 |
| branches | string | 否 | 特征分支选择，使用 g/l/f/t 字母组合（如 "glf"），默认 "glft"（全部）。其中：g=全局特征，l=局部特征，f=脸部特征，t=文本特征 |
| meta_json | string | 否 | 元数据 JSON 字符串，可包含 desc 等信息 |

请求示例（/api/extract_upload）：

```bash
curl -X POST "http://127.0.0.1:8030/api/extract_upload" \
  -F "images=@path/to/image1.jpg" \
  -F "images=@path/to/image2.jpg" \
  -F "return_type=all" \
  -F "desc=这是一只金毛犬" \
  -F "branches=glft"
```

返回结构（示例）：

```json
{
  "features_present": {
    "global": {
      "present": true,
      "size": 768
    },
    "face": {
      "present": true,
      "size": 512
    },
    "local": {
      "present": true,
      "size": 768
    },
    "text": {
      "present": true,
      "size": 768
    }
  },
  "timings": {
    "decode_ms": 76.83410216122866,
    "encode_ms": 7840.106944087893,
    "total_ms": 7917.856342159212,
    "stages": {
      "init": {
        "pipeline_init_ms": 0.0
      },
      "global": {
        "encode_ms": 878.568593878299
      },
      "face": {
        "encode_ms": 4706.214942038059
      },
      "local": {
        "encode_ms": 1535.7017437927425
      },
      "text": {
        "encode_ms": 200.00290777534246
      },
      "seg": {
        "encode_ms": 468.9689250662923
      }
    }
  }
}
```

## 本地 API 测试工具

### test.py 使用说明

`test.py` 是一个本地 API 客户端工具，用于测试特征提取接口，支持以下功能：

- 上传单个图像文件或目录下的所有图像
- 发送自定义描述文本
- 选择特征分支
- 保存完整的 JSON 响应
- 显示特征存在性摘要

#### 使用示例

```bash
# 测试单个图像文件
python test.py --path "path/to/image.jpg" --api http://127.0.0.1:8030 --desc "a cute dog"

# 测试目录下的所有图像
python test.py --path "path/to/images/" --api http://127.0.0.1:8030 --desc "multiple dogs"

# 选择特定特征分支
python test.py --path "path/to/image.jpg" --branches "glf" --desc "a dog with face"

# 保存响应到文件
python test.py --path "path/to/image.jpg" --save "response.json" --desc "test dog"
```

#### 参数说明

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| --path | string | 是 | 图像文件或目录路径 |
| --api | string | 否 | API 基础 URL，默认从配置或环境变量获取 |
| --desc | string | 否 | 描述文本，默认 "local test description" |
| --save | string | 否 | 保存完整 JSON 响应的路径 |
| --branches | string | 否 | 特征分支选择，默认 "glft" |

## 基准测试与排查

### 1) 单条接口耗时（curl）

使用 curl 直接测试单条请求耗时（Windows/PowerShell 同样适用）：

```bash
curl -X POST "http://180.97.221.107:8030/api/extract_upload" \
  -F "images=@data/queries/my_dog/0.jpg" -F "return_type=all" \
  -w "status=%{http_code} time_total=%{time_total}s\n" -o /dev/null -s
```

### 2) 单条接口耗时（Python 脚本）

```bash
python scripts/bench_api_single.py --image data/queries/my_dog/0.jpg --runs 5 --session --local
```

## 许可与致谢

- 模型与数据的版权归原作者所有；请遵循相应许可协议。
- 致谢开源社区对 SigLIP/SigLIP2 与宠物识别相关工作的贡献。

 

## 常见问题（FAQ）

- 普通 OSS 连接失败：检查 `oss.normal.endpoint`、`oss.normal.bucket`、`oss.access_key_id`、`oss.access_key_secret` 是否正确，账号是否有写入权限。
- 向量 OSS 连接失败：检查 `oss.vector.endpoint`、`oss.vector.bucket`、`oss.vector.region`、`oss.vector.account_id` 是否正确，账号是否有向量操作权限。
- OSS Key 冲突或覆盖：建议使用 `oss.prefix` 按数据集/宠物 ID 分层组织。
- 中文乱码（YAML/注释）：项目文件均为 UTF-8 编码，确保编辑器保存为 UTF-8（无 BOM）。