# logistics-agent

**Repository Path**: he-jiangbai/logistics-agent

## Basic Information

- **Project Name**: logistics-agent
- **Description**: 智能电商物流系统
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-23
- **Last Updated**: 2025-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Logistics-AI-Query 系统

# Logistics-AI-Query

基于 Django 框架构建的物流 AI 查询系统，集成阿里灵积（Dashscope）大模型，通过自然语言生成 SQL 查询物流数据，实现智能化的物流信息检索。

## 项目架构
- **后端框架**：Django 5.2.8（Web 服务与路由管理）
- **AI 能力**：langchain-community 0.4.0（LLM 链管理）+ 阿里 Dashscope（Qwen 系列模型，如 qwen3-max）
- **数据库**：MySQL（存储物流与承运商数据）
- **环境配置**：python-dotenv（管理敏感配置，如 API Key、数据库信息）

## 环境配置
### 1. 环境变量（.env 文件）
项目敏感配置通过 `.env` 文件管理，需在项目根目录创建该文件并添加以下内容（未上传至仓库）：
```ini
# Django 配置
DEBUG=False
SECRET_KEY=your_django_secret_key
ALLOWED_HOSTS=localhost,127.0.0.1

# 数据库配置
DB_NAME=logistics_db
DB_USER=root
DB_PASSWORD=your_db_password
DB_HOST=localhost
DB_PORT=3306

# 阿里 Dashscope 配置
DASHSCOPE_API_KEY=your_dashscope_api_key
```

### 2. 依赖安装
```bash
# 安装核心依赖 
pip install -r requirements.txt
```

## 开放接口
目前仅开放物流 AI 查询接口：

### 接口地址
`POST /logistics-ai/query/`

### 请求体格式
```json
{
    "query": "从深圳发往漳州的异常件有哪些？"
}
```

### 响应格式
- 成功响应：
```json
{
    "status": "success",
    "summary": "您好！已为您查询发往闽南地区的快递情况。\n\n目前共查询到 **1 条** 发往闽南地区的快递记录，具体信息如下：\n\n- **快递单号**：SF20251123002  \n- **始发地**：深圳  \n- **目的地**：漳州（属于闽南地区）  \n- **当前状态**：异常  \n- **异常原因**：收件人地址不详  \n- **最新动态**：派送失败，等待收件人联系快递员  \n- **最后更新时间**：2025年11月23日 18:45  \n\n建议您尽快联系快递公司（该单由顺丰承运）或确认收件地址是否准确，以便顺利派送。需要我帮您联系客服或提供进一步协助吗？",
    "generated_sql": "SELECT *\nFROM shipments\nWHERE destination_city IN ('厦门',\n                           '漳州',\n                           '泉州');",
    "raw_results": [
        {
            "id": 51,
            "tracking_no": "SF20251123002",
            "order_no": null,
            "origin_city": "深圳",
            "destination_city": "漳州",
            "status": "EXCEPTION",
            "is_exception": 1,
            "exception_reason": "收件人地址不详",
            "last_event": "派送失败，待收件人联系",
            "last_event_time": "2025-11-23T18:45:00",
            "delivered_at": null,
            "last_raw": null,
            "created_at": "2025-11-23T21:23:44.974511",
            "updated_at": "2025-11-23T21:23:44.974511",
            "carrier_id": 1
        }
    ],
    "count": 1
}
```

- 失败响应：
```json
{
    "status": "error",
    "message": "SQL执行错误或生成失败",
    "generated_sql": "错误的SQL语句"
}
```

## 核心文件说明
### 1. `logistics_ai/llm_chain.py`
- 定义 LLM 调用链：包含 Prompt 模板设计（约束模型生成符合表结构的 SQL）、Dashscope 模型初始化（指定模型名、温度等参数）。
- 实现自然语言到 SQL 的转换逻辑：接收用户查询文本，通过 langchain 链调用大模型生成 SQL，返回结构化结果。
- 关键功能：Prompt 规则约束（如禁止虚构字段、指定关联关系）、模型调用参数配置。

### 2. `logistics_ai/utils.py`
- 数据库 Schema 生成：从 Django 模型动态提取表结构（字段名、类型、外键关联），生成 AI 友好的 Schema 描述，确保模型生成 SQL 的准确性。
- 辅助工具函数：如 SQL 执行校验、数据格式化处理等（可扩展）。

### 3. `logistics_ai/views.py`
- 接口视图层：处理 `query` 接口的 HTTP 请求，解析请求体中的自然语言查询。
- 业务逻辑协调：调用 `llm_chain` 生成 SQL，执行 SQL 查询数据库，封装响应结果（成功/失败状态、数据或错误信息）。
- 异常处理：捕获 SQL 执行错误、模型调用异常等，返回友好的错误提示。

## 使用步骤
1. 配置 `.env` 文件（填写数据库信息、Dashscope API Key）；
2. 执行数据库迁移，初始化表结构：`python manage.py migrate`；
3. 启动 Django 服务：`python manage.py runserver`；
4. 通过 POST 请求调用 `/logistics-ai/query/` 接口，传入自然语言查询即可获取结果。