# Feature-Library

**Repository Path**: langdawei/feature-library

## Basic Information

- **Project Name**: Feature-Library
- **Description**: 基于Qwen3系列模型（Qwen3-VL、Qwen3-VL-Embedding、Qwen3-VL-Reranker）构建的大件货物特征识别系统。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-15
- **Last Updated**: 2026-02-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 大件货物特征库识别系统

基于Qwen3系列模型（Qwen3-VL、Qwen3-VL-Embedding、Qwen3-VL-Reranker）构建的大件货物特征识别系统。

## 系统架构

本系统包含三个核心组件：

1. **Qwen3-VL**：负责大件货物图像的视觉语言理解
2. **Qwen3-VL-Embedding**：将图像和文本转换为特征向量
3. **Qwen3-VL-Reranker**：对检索结果进行重排序优化

## 依赖要求

- transformers>=4.57.0
- qwen-vl-utils>=0.0.14
- torch==2.8.0
- torchvision
- Pillow
- numpy
- requests
- fastapi
- uvicorn
- pydantic

## 快速开始

### 1. 安装依赖

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

### 2. 部署本地模型（如果模型在本地）

如果您的Qwen3-VL-Embedding-8B和Qwen3-VL-Reranker-2B模型在本地，请运行：

```bash
python deploy_models.py
```

脚本会提示您输入本地模型路径，然后自动部署到项目目录。

### 3. 运行API服务

```bash
python main.py
```

或者使用Docker：

```bash
docker-compose up -d
```

### 4. API端点

- `POST /api/v1/vl-analyze` - 图像分析
- `POST /api/v1/embed` - 特征嵌入
- `POST /api/v1/rerank` - 结果重排序

## 使用方法

### 1. API调用

系统提供以下API端点：

- `POST /api/v1/vl-analyze` - 图像分析
- `POST /api/v1/embed` - 特征嵌入
- `POST /api/v1/rerank` - 结果重排序
- `POST /api/v1/embed-text` - 文本嵌入
- `POST /api/v1/embed-image` - 图像嵌入
- `POST /api/v1/embed-multimodal` - 多模态嵌入
- `POST /api/v1/simple-rerank` - 简单重排序

### 2. Python客户端

系统提供Python客户端用于便捷调用：

```python
from client import CargoFeatureClient

# 创建客户端实例
client = CargoFeatureClient(base_url="http://localhost:8000")

# 图像分析
result = client.analyze_image(
    image_source="https://example.com/heavy_equipment/digger.jpg",
    prompt="请详细描述这张图片中的大件货物"
)

# 文本嵌入
embedding = client.get_text_embedding("大型机械设备，带有红色涂装")

# 批量嵌入
inputs = [
    {"text": "大型机械设备，带有红色涂装"},
    {"image": "https://example.com/equipment.jpg"}
]
embeddings = client.get_embeddings(inputs)

# 结果重排序
result = client.simple_rerank(
    query="大型工程机械，履带式挖掘机",
    candidates=[
        "大型履带式挖掘机，黄色涂装",
        "标准海运集装箱"
    ]
)
```

### 3. 启动脚本

系统提供一键启动脚本：

```bash
# 运行启动脚本
python launch.py
```

脚本提供以下选项：
- 启动服务
- 启动客户端
- 启动服务并运行客户端示例
- 运行高级示例

### 4. 高级使用示例

运行高级示例了解完整的应用场景：

```bash
python advanced_demo.py
```

示例包含：
- 特征库构建
- 相似货物搜索
- 货物识别
- 结果重排序

## 配置

系统支持以下环境变量配置：

- `QWEN3_VL_MODEL_PATH`: Qwen3-VL模型路径
- `QWEN3_EMBEDDING_MODEL_PATH`: Qwen3-VL-Embedding模型路径
- `QWEN3_RERANKER_MODEL_PATH`: Qwen3-VL-Reranker模型路径
- `DEVICE`: 运行设备 (cuda/cpu)
- `TORCH_DTYPE`: 模型精度 (float16/bfloat16)
- `USE_FLASH_ATTENTION`: 是否使用Flash Attention
- `BATCH_SIZE`: 批处理大小
- `API_HOST`: API服务主机
- `API_PORT`: API服务端口

## 应用场景

本系统专为大件货物特征库识别设计，适用于：

- 物流仓储中的货物识别
- 海关监管中的货物分类
- 工业制造中的物料管理
- 供应链管理中的库存盘点

## 许可证

本项目采用MIT许可证。