ai_job_chat_agent/API_DOCS.md

# 青岛岗位匹配系统 API 调用文档

> **版本**: 1.0.0  
> **更新日期**: 2025-11  
> **协议**: 兼容 OpenAI Chat Completions API

---

## 目录

- [1. 系统概述](#1-系统概述)
- [2. 系统架构](#2-系统架构)
- [3. 快速开始](#3-快速开始)
- [4. API 端点列表](#4-api-端点列表)
- [5. 核心接口详解](#5-核心接口详解)
  - [5.1 聊天补全接口](#51-聊天补全接口)
  - [5.2 健康检查接口](#52-健康检查接口)
  - [5.3 性能指标接口](#53-性能指标接口)
  - [5.4 性能分析接口](#54-性能分析接口)
- [6. 内置工具说明](#6-内置工具说明)
- [7. 代码对照表](#7-代码对照表)
- [8. SDK 与代码示例](#8-sdk-与代码示例)
- [9. 错误处理](#9-错误处理)
- [10. 配置参考](#10-配置参考)
- [11. 部署指南](#11-部署指南)
- [12. 常见问题](#12-常见问题)

---

## 1. 系统概述

### 1.1 系统简介

青岛岗位匹配系统是一个基于 Go 语言开发的智能岗位推荐服务，提供与 OpenAI `/v1/chat/completions` 完全兼容的 API 接口。系统集成了多种智能工具，能够自动理解用户意图并调用相应功能。

### 1.2 核心功能

| 功能模块 | 说明 |
|---------|------|
| 🎯 **岗位推荐** | 根据用户需求、简历内容智能推荐青岛市岗位 |
| 📍 **地理位置查询** | 集成高德地图，支持按位置、区域搜索岗位 |
| 📄 **文件解析** | 支持 PDF、图片、Excel、PPT、Word 等文件的 OCR 智能解析 |
| 🖼️ **Vision API** | 兼容 OpenAI Vision API 格式，支持通过 URL 发送图片/PDF/Excel/PPT 等文件进行 OCR 识别 |
| 📋 **政策咨询** | 提供就业创业、社保医保、人才政策等咨询服务 |
| 🔄 **多轮对话** | 支持上下文连续对话 |
| ⚡ **流式输出** | 支持 SSE 流式响应，提升用户体验 |

### 1.3 技术特性

- **兼容性**: 100% 兼容 OpenAI Chat API 格式
- **高性能**: 基于 Gin 框架，支持高并发
- **限流保护**: 内置令牌桶限流（200 容量/50 QPS）
- **优雅关闭**: 支持信号处理和优雅停机
- **可观测性**: 内置 JSON 指标端点和 pprof 性能分析（可通过配置开关关闭）

---

## 2. 系统架构

### 2.1 架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                        客户端 (Client)                          │
│            (Web/App/第三方 OpenAI 兼容客户端)                    │
└─────────────────────────────┬───────────────────────────────────┘
                              │ HTTP/HTTPS
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      API 网关层 (Gateway)                        │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐  │
│  │  CORS   │ │ Recovery│ │ Metrics │ │  Rate   │ │  Logger  │  │
│  │Middleware│ │Middleware│ │Middleware│ │ Limit  │ │          │  │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘  │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      处理器层 (Handlers)                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ ChatHandler  │  │HealthHandler │  │MetricsHandler│          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      服务层 (Services)                           │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐               │
│  │ ChatService │ │ JobService  │ │FileService  │               │
│  └─────────────┘ └─────────────┘ └─────────────┘               │
│  ┌─────────────┐ ┌─────────────┐                               │
│  │LocationServ │ │PolicyService│                               │
│  └─────────────┘ └─────────────┘                               │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      客户端层 (Clients)                          │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐       │
│  │ LLMClient │ │ JobClient │ │AmapClient │ │ OCRClient │       │
│  └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘       │
│        │             │             │             │              │
└────────┼─────────────┼─────────────┼─────────────┼──────────────┘
         │             │             │             │
         ▼             ▼             ▼             ▼
┌──────────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────────┐
│   LLM API    │ │  岗位 API    │ │ 高德地图  │ │  OCR 服务   │
│ (OpenAI兼容) │ │              │ │   API    │ │             │
└──────────────┘ └──────────────┘ └──────────┘ └──────────────┘
```

### 2.2 数据流

```
用户请求 → 中间件处理 → ChatHandler → ChatService 
                                          ↓
                               识别意图 & 调用工具
                                          ↓
                         ┌────────────────┼────────────────┐
                         ↓                ↓                ↓
                   LocationService   JobService    PolicyService
                         ↓                ↓                ↓
                    高德地图API       岗位API         政策API
                         ↓                ↓                ↓
                         └────────────────┼────────────────┘
                                          ↓
                               整合结果 & 生成回复
                                          ↓
                              流式/非流式响应 → 用户
```

---

## 3. 快速开始

### 3.1 环境要求

- Go 1.20+
- 或 Docker 20.10+

### 3.2 安装运行

#### 方式一：源码运行

```bash
# 克隆项目
git clone <repository-url>
cd qd-sc

# 安装依赖
go mod download

# 配置文件（编辑 config.yaml）
cp config.yaml config.local.yaml
vim config.local.yaml

# 运行
go run cmd/server/main.go

# 或编译后运行
go build -o qd-sc-server cmd/server/main.go
./qd-sc-server -config=config.yaml
```

#### 方式二：Docker 运行

```bash
# 使用 docker-compose
docker-compose up -d

# 或手动构建
docker build -t qd-sc-server .
docker run -d -p 8080:8080 \
  -e LLM_API_KEY="sk-xxx" \
  -e LLM_BASE_URL="https://your-api.com/v1" \
  --name qd-sc-server \
  qd-sc-server
```

### 3.3 验证服务

```bash
# 健康检查
curl http://localhost:8080/health

# 测试对话（流式）
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qd-job-turbo",
    "messages": [{"role": "user", "content": "推荐城阳区的Java开发岗位"}],
    "stream": true
  }'
```

---

## 4. API 端点列表

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/` | GET | API 信息和端点列表 | 无 |
| `/health` | GET | 健康检查 | 无 |
| `/metrics` | GET | 性能指标（JSON，需启用 `performance.enable_metrics`） | 无 |
| `/v1/chat/completions` | POST | **核心接口** - OpenAI 兼容的聊天接口 | 无 |
| `/debug/pprof/*` | GET | pprof 性能分析（需启用 `performance.enable_pprof`） | 无 |

---

## 5. 核心接口详解

### 5.1 聊天补全接口

#### 基本信息

| 属性 | 值 |
|------|-----|
| **端点** | `POST /v1/chat/completions` |
| **Content-Type** | `application/json` |
| **响应格式** | JSON 或 SSE (Server-Sent Events) |

#### 5.1.1 JSON 请求格式

```http
POST /v1/chat/completions HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "model": "qd-job-turbo",
  "messages": [
    {
      "role": "system",
      "content": "你是一个有帮助的助手"
    },
    {
      "role": "user",
      "content": "帮我找青岛城阳区的Java开发岗位"
    }
  ],
  "stream": true,
  "temperature": 0.7,
  "max_tokens": 2000
}
```

#### 5.1.2 请求参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `model` | string | ✅ | - | 模型名称，固定为 `qd-job-turbo` |
| `messages` | array | ✅ | - | 消息数组，见下表 |
| `stream` | boolean | ❌ | `false` | 是否流式输出（**推荐 `true`**） |
| `temperature` | float | ❌ | `1.0` | 采样温度，范围 0-2 |
| `top_p` | float | ❌ | `1.0` | 核采样参数 |
| `max_tokens` | integer | ❌ | - | 最大生成 token 数 |
| `presence_penalty` | float | ❌ | `0.0` | 存在惩罚，范围 -2.0 到 2.0 |
| `frequency_penalty` | float | ❌ | `0.0` | 频率惩罚，范围 -2.0 到 2.0 |
| `user` | string | ❌ | - | 用户标识 |

#### 5.1.3 消息对象格式

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `role` | string | ✅ | 角色：`system`、`user`、`assistant` |
| `content` | string/array | ✅ | 消息内容（支持文本或多模态数组） |
| `name` | string | ❌ | 发送者名称 |

**role 说明**:

| 角色 | 说明 |
|------|------|
| `system` | 系统指令，设置 AI 行为 |
| `user` | 用户消息 |
| `assistant` | AI 回复 |

**content 格式说明**:

`content` 支持两种格式：

1. **字符串格式**（普通文本消息）：
```json
{
  "role": "user",
  "content": "帮我推荐Java开发岗位"
}
```

2. **数组格式**（多模态消息，支持图片 - OpenAI Vision API 兼容）：
```json
{
  "role": "user",
  "content": [
    {"type": "text", "text": "根据这份简历帮我推荐合适的岗位"},
    {"type": "image_url", "image_url": {"url": "https://example.com/resume.jpg"}}
  ]
}
```

**多模态内容类型**:

| type | 说明 | 字段 |
|------|------|------|
| `text` | 文本内容 | `text`: 文本字符串 |
| `image_url` | 文件URL（兼容字段） | `image_url.url`: 文件地址 |

> **重要说明**: 
> - `image_url` 是为兼容 OpenAI Vision API 而保留的字段名称
> - 实际上不仅支持图片，**还支持 PDF、Excel、PPT 等所有 OCR 服务支持的文件类型**
> - 系统会自动调用 OCR 服务进行识别解析
> - 支持的文件格式：JPG、PNG、GIF、PDF、XLS、XLSX、PPT、PPTX 等

#### 5.1.4 带文件URL的请求（Vision API 兼容格式）

完全兼容 OpenAI Vision API 格式，通过 `image_url` 字段发送文件 URL 进行 OCR 识别。

> **字段说明**: `image_url` 是 OpenAI Vision API 的标准字段名，为保持兼容性沿用此名称。但本系统通过 OCR 服务，**不仅支持图片，还支持 PDF、Excel、PPT 等多种文件格式**。

**示例 1：发送图片简历**

```http
POST /v1/chat/completions HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "model": "qd-job-turbo",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "根据这份简历帮我推荐合适的岗位"},
        {"type": "image_url", "image_url": {"url": "https://example.com/resume.jpg"}}
      ]
    }
  ],
  "stream": true
}
```

**示例 2：发送 PDF 文件**

```json
{
  "role": "user",
  "content": [
    {"type": "text", "text": "分析这份PDF简历"},
    {"type": "image_url", "image_url": {"url": "https://example.com/resume.pdf"}}
  ]
}
```

**示例 3：发送 Excel 文件**

```json
{
  "role": "user",
  "content": [
    {"type": "text", "text": "帮我分析这个表格数据"},
    {"type": "image_url", "image_url": {"url": "https://example.com/data.xlsx"}}
  ]
}
```

**示例 4：发送多个文件**

```json
{
  "role": "user",
  "content": [
    {"type": "text", "text": "分析这些文档内容"},
    {"type": "image_url", "image_url": {"url": "https://example.com/resume.pdf"}},
    {"type": "image_url", "image_url": {"url": "https://example.com/certificate.jpg"}},
    {"type": "image_url", "image_url": {"url": "https://example.com/transcript.xlsx"}}
  ]
}
```

**支持的文件格式**:

| 类型 | 格式 |
|------|------|
| 图片 | JPG、JPEG、PNG、GIF |
| 文档 | PDF |
| 表格 | XLS、XLSX |
| 演示 | PPT、PPTX |

#### 5.1.6 流式响应格式 (SSE)

当 `stream: true` 时，响应为 Server-Sent Events 格式：

```
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qd-job-turbo","choices":[{"index":0,"delta":{"role":"assistant","content":"您好"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qd-job-turbo","choices":[{"index":0,"delta":{"content":"，"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qd-job-turbo","choices":[{"index":0,"delta":{"content":"我"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"qd-job-turbo","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

**Chunk 对象结构**:

```typescript
interface ChatCompletionChunk {
  id: string;                    // 响应ID
  object: "chat.completion.chunk";
  created: number;               // Unix 时间戳
  model: string;                 // 模型名称
  choices: Array<{
    index: number;
    delta: {
      role?: "assistant";        // 仅首个 chunk 包含
      content?: string;          // 内容片段
    };
    finish_reason: string | null; // "stop" 或 null
  }>;
}
```

#### 5.1.7 非流式响应格式

当 `stream: false` 时：

```json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "qd-job-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "您好，我可以帮您推荐岗位..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 50,
    "total_tokens": 150
  }
}
```

#### 5.1.8 岗位推荐特殊响应格式

当系统返回岗位推荐时，岗位信息会以特殊的 Markdown 代码块格式输出：

```
为您找到 3 个相关岗位：

``` job-json
{
  "jobTitle": "Java开发工程师",
  "companyName": "青岛XX科技有限公司",
  "salary": "15000-25000元/月",
  "location": "城阳区",
  "education": "本科",
  "experience": "3-5年",
  "appJobUrl": "https://..."
}
```

``` job-json
{
  "jobTitle": "高级Java工程师",
  "companyName": "青岛YY信息技术有限公司",
  "salary": "20000-35000元/月",
  "location": "城阳区",
  "education": "本科",
  "experience": "5-10年",
  "appJobUrl": "https://..."
}
```
```

**岗位对象结构**:

```typescript
interface FormattedJob {
  jobTitle: string;      // 职位名称
  companyName: string;   // 公司名称
  salary: string;        // 薪资范围
  location: string;      // 工作地点
  education: string;     // 学历要求
  experience: string;    // 经验要求
  appJobUrl: string;     // 职位详情链接
  data?: any;            // 额外数据（分页信息等）
}
```

---

### 5.2 健康检查接口

#### 请求

```http
GET /health HTTP/1.1
Host: localhost:8080
```

#### 响应

```json
{
  "status": "ok",
  "timestamp": "2024-01-01T12:00:00Z"
}
```

---

### 5.3 性能指标接口

> 该接口需要启用 `performance.enable_metrics`；关闭后将不会注册 `/metrics` 端点。

#### 请求

```http
GET /metrics HTTP/1.1
Host: localhost:8080
```

#### 响应

```json
{
  "requests_total": 12345,
  "requests_success": 12300,
  "requests_failed": 45,
  "avg_response_time_ms": 156.8,
  "goroutines": 42,
  "memory_alloc_mb": 45.6
}
```

| 指标 | 说明 |
|------|------|
| `requests_total` | 总请求数 |
| `requests_success` | 成功请求数 |
| `requests_failed` | 失败请求数 |
| `avg_response_time_ms` | 平均响应时间（毫秒） |
| `goroutines` | 当前 goroutine 数量 |
| `memory_alloc_mb` | 内存分配（MB） |

---

### 5.4 性能分析接口

> 该接口需要启用 `performance.enable_pprof`；关闭后将不会注册 `/debug/pprof/*` 端点。

支持 Go pprof 标准端点：

| 端点 | 说明 |
|------|------|
| `/debug/pprof/` | pprof 索引页面 |
| `/debug/pprof/profile?seconds=30` | CPU 性能分析 |
| `/debug/pprof/heap` | 堆内存分析 |
| `/debug/pprof/goroutine` | Goroutine 分析 |
| `/debug/pprof/allocs` | 内存分配分析 |

**使用示例**:

```bash
# 采集 30 秒 CPU 数据
curl http://localhost:8080/debug/pprof/profile?seconds=30 -o cpu.prof

# 分析
go tool pprof cpu.prof
```

---

## 6. 内置工具说明

系统内置了多种智能工具，会根据用户意图自动调用：

### 6.1 queryLocation - 地理位置查询

**功能**: 查询青岛具体地点的经纬度坐标

**触发场景**: 用户提到具体地点名称时（如"五四广场附近"、"青岛啤酒博物馆周边"）

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `keywords` | string | ✅ | 地点名称，如"五四广场" |

**返回示例**:

```json
{
  "keywords": "五四广场",
  "latitude": "36.061892",
  "longitude": "120.384428",
  "message": "成功获取地点 五四广场 的坐标"
}
```

---

### 6.2 queryJobsByArea - 按区域查询岗位

**功能**: 根据青岛市区域代码查询岗位信息

**触发场景**: 用户指定区域名称时（如"城阳区"、"市北区"）

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `jobTitle` | string | ✅ | - | 岗位关键词 |
| `current` | integer | ✅ | 1 | 页码 |
| `pageSize` | integer | ✅ | 10 | 每页数量 |
| `jobLocationAreaCode` | string | ❌ | - | 区域代码（见代码表） |
| `order` | string | ❌ | "0" | 排序：0-推荐，1-最热，2-最新 |
| `minSalary` | string | ❌ | - | 最低薪资（元/月） |
| `maxSalary` | string | ❌ | - | 最高薪资（元/月） |
| `experience` | string | ❌ | - | 经验要求代码 |
| `education` | string | ❌ | - | 学历要求代码 |
| `companyNature` | string | ❌ | - | 企业类型代码 |

---

### 6.3 queryJobsByLocation - 按坐标查询岗位

**功能**: 根据经纬度和半径查询附近岗位

**触发场景**: 用户指定具体地点后，需要查询附近岗位

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `jobTitle` | string | ✅ | - | 岗位关键词 |
| `current` | integer | ✅ | 1 | 页码 |
| `pageSize` | integer | ✅ | 10 | 每页数量 |
| `latitude` | string | ✅ | - | 纬度 |
| `longitude` | string | ✅ | - | 经度 |
| `radius` | string | ✅ | "10" | 搜索半径（千米，最大50） |
| `order` | string | ❌ | "0" | 排序方式 |
| `minSalary` | string | ❌ | - | 最低薪资 |
| `maxSalary` | string | ❌ | - | 最高薪资 |
| `experience` | string | ❌ | - | 经验要求 |
| `education` | string | ❌ | - | 学历要求 |
| `companyNature` | string | ❌ | - | 企业类型 |

---

### 6.4 queryPolicy - 政策咨询

**功能**: 查询青岛市就业创业、社保医保、人才政策等

**触发场景**: 用户咨询政策相关问题

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `message` | string | ✅ | - | 咨询问题 |
| `chatId` | string | ❌ | - | 会话ID（多轮对话） |
| `conversationId` | string | ❌ | - | 流水号（多轮对话） |
| `realName` | boolean | ❌ | false | 是否实名咨询 |
| `aac001` | string | ❌* | - | 个人编号（实名时必填） |
| `aac147` | string | ❌* | - | 身份证号（实名时必填） |
| `aac003` | string | ❌* | - | 姓名（实名时必填） |

---

### 6.5 parsePDF - PDF 解析

**功能**: 使用 OCR 服务解析 PDF 文件内容（如简历）

**说明**: 通常在文件上传时自动触发，无需手动调用。文件会通过 OCR 服务进行识别解析。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `fileUrl` | string | ✅ | PDF 文件 URL |

---

### 6.6 parseImage - 图片解析

**功能**: 使用 OCR 服务识别图片中的文本内容

**说明**: 通常在文件上传时自动触发，无需手动调用。文件会通过 OCR 服务进行识别解析。

**参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `imageUrl` | string | ✅ | 图片文件 URL |

---

## 7. 代码对照表

### 7.1 区域代码 (jobLocationAreaCode)

| 代码 | 区域 |
|------|------|
| 0 | 市南区 |
| 1 | 市北区 |
| 2 | 李沧区 |
| 3 | 崂山区 |
| 4 | 黄岛区 |
| 5 | 城阳区 |
| 6 | 即墨区 |
| 7 | 胶州市 |
| 8 | 平度市 |
| 9 | 莱西市 |

### 7.2 学历代码 (education)

| 代码 | 学历 |
|------|------|
| -1 | 学历不限 |
| 0 | 初中及以下 |
| 1 | 中专/中技 |
| 2 | 高中 |
| 3 | 大专 |
| 4 | 本科 |
| 5 | 硕士 |
| 6 | 博士 |
| 7 | MBA/EMBA |
| 8 | 留学-学士 |
| 9 | 留学-硕士 |
| 10 | 留学-博士 |

### 7.3 经验代码 (experience)

| 代码 | 经验 |
|------|------|
| 0 | 经验不限 |
| 1 | 实习生 |
| 2 | 应届毕业生 |
| 3 | 1年以下 |
| 4 | 1-3年 |
| 5 | 3-5年 |
| 6 | 5-10年 |
| 7 | 10年以上 |

### 7.4 企业类型代码 (companyNature)

| 代码 | 类型 |
|------|------|
| 1 | 私营企业 |
| 2 | 股份制企业 |
| 3 | 国有企业 |
| 4 | 外商及港澳台投资企业 |
| 5 | 医院 |

### 7.5 排序方式代码 (order)

| 代码 | 排序 |
|------|------|
| 0 | 推荐 |
| 1 | 最热 |
| 2 | 最新发布 |

---

## 8. SDK 与代码示例

### 8.1 cURL 示例

#### 基础对话

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qd-job-turbo",
    "messages": [
      {"role": "user", "content": "帮我推荐城阳区的Java开发岗位"}
    ],
    "stream": true
  }'
```

#### 带文件URL（Vision API 兼容格式）

通过 `image_url` 字段发送文件 URL（支持图片、PDF、Excel、PPT 等）：

```bash
# 发送图片
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qd-job-turbo",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "根据这份简历帮我推荐合适的岗位"},
          {"type": "image_url", "image_url": {"url": "https://example.com/resume.jpg"}}
        ]
      }
    ],
    "stream": true
  }'

# 发送 PDF 文件
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qd-job-turbo",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "分析这份PDF简历"},
          {"type": "image_url", "image_url": {"url": "https://example.com/resume.pdf"}}
        ]
      }
    ],
    "stream": true
  }'
```

#### 多轮对话

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qd-job-turbo",
    "messages": [
      {"role": "user", "content": "我想找Java开发岗位"},
      {"role": "assistant", "content": "好的，请问您希望在青岛哪个区域工作？"},
      {"role": "user", "content": "城阳区，要求薪资15k以上"}
    ],
    "stream": true
  }'
```

#### 政策咨询

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qd-job-turbo",
    "messages": [
      {"role": "user", "content": "青岛市大学生就业补贴政策是怎样的？"}
    ],
    "stream": true
  }'
```

---

### 8.2 Python 示例

#### 使用 OpenAI SDK

```python
from openai import OpenAI

# 创建客户端，指向本地服务
client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # 本系统不需要 API key
)

# 流式对话
def chat_stream(message: str):
    stream = client.chat.completions.create(
        model="qd-job-turbo",
        messages=[{"role": "user", "content": message}],
        stream=True
    )
    
    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
    print()

# 示例
chat_stream("帮我推荐青岛城阳区的Java开发岗位")
```

#### 使用 Vision API 兼容格式发送文件 URL

通过 `image_url` 字段发送文件 URL，支持图片、PDF、Excel、PPT 等格式：

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)

# 带文件URL的对话（Vision API 兼容格式）
# 注意：image_url 是兼容字段名，实际支持多种文件格式
def chat_with_file_url(text: str, file_url: str):
    stream = client.chat.completions.create(
        model="qd-job-turbo",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": text},
                    {"type": "image_url", "image_url": {"url": file_url}}
                ]
            }
        ],
        stream=True
    )
    
    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
    print()

# 示例1：发送图片简历
chat_with_file_url(
    "根据这份简历帮我推荐合适的岗位",
    "https://example.com/resume.jpg"
)

# 示例2：发送 PDF 文件
chat_with_file_url(
    "分析这份PDF文档",
    "https://example.com/document.pdf"
)

# 示例3：发送 Excel 文件
chat_with_file_url(
    "帮我分析这个表格",
    "https://example.com/data.xlsx"
)
```

#### 使用 Requests 库

```python
import requests
import json

def chat_with_file(message: str, file_path: str = None):
    url = "http://localhost:8080/v1/chat/completions"
    
    if file_path:
        # 带文件上传
        files = {
            'file': open(file_path, 'rb'),
            'request': (None, json.dumps({
                "model": "qd-job-turbo",
                "messages": [{"role": "user", "content": message}],
                "stream": True
            }))
        }
        response = requests.post(url, files=files, stream=True)
    else:
        # 普通请求
        response = requests.post(
            url,
            json={
                "model": "qd-job-turbo",
                "messages": [{"role": "user", "content": message}],
                "stream": True
            },
            stream=True
        )
    
    # 处理流式响应
    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')
            if line.startswith('data: '):
                data = line[6:]
                if data == '[DONE]':
                    break
                chunk = json.loads(data)
                if chunk['choices'][0]['delta'].get('content'):
                    print(chunk['choices'][0]['delta']['content'], end='', flush=True)
    print()

# 示例
chat_with_file("根据我的简历推荐岗位", "resume.pdf")
```

---

### 8.3 JavaScript/TypeScript 示例

#### 使用 Fetch API

```typescript
interface ChatMessage {
  role: 'system' | 'user' | 'assistant';
  content: string;
}

async function chat(messages: ChatMessage[]): Promise<void> {
  const response = await fetch('http://localhost:8080/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'qd-job-turbo',
      messages,
      stream: true,
    }),
  });

  const reader = response.body?.getReader();
  const decoder = new TextDecoder();

  if (!reader) return;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const text = decoder.decode(value);
    const lines = text.split('\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = line.slice(6);
        if (data === '[DONE]') return;

        try {
          const chunk = JSON.parse(data);
          const content = chunk.choices[0]?.delta?.content;
          if (content) {
            process.stdout.write(content);
          }
        } catch (e) {
          // 忽略解析错误
        }
      }
    }
  }
}

// 使用示例
chat([
  { role: 'user', content: '帮我推荐城阳区的Java开发岗位' }
]);
```

#### 使用 OpenAI SDK (Node.js)

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8080/v1',
  apiKey: 'not-needed',
});

async function chatStream(message: string) {
  const stream = await client.chat.completions.create({
    model: 'qd-job-turbo',
    messages: [{ role: 'user', content: message }],
    stream: true,
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
  }
  console.log();
}

chatStream('帮我推荐青岛城阳区的Java开发岗位');
```

---

### 8.4 Go 示例

```go
package main

import (
    "bufio"
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "strings"
)

type ChatRequest struct {
    Model    string    `json:"model"`
    Messages []Message `json:"messages"`
    Stream   bool      `json:"stream"`
}

type Message struct {
    Role    string `json:"role"`
    Content string `json:"content"`
}

func chat(message string) error {
    req := ChatRequest{
        Model: "qd-job-turbo",
        Messages: []Message{
            {Role: "user", Content: message},
        },
        Stream: true,
    }

    body, _ := json.Marshal(req)
    resp, err := http.Post(
        "http://localhost:8080/v1/chat/completions",
        "application/json",
        bytes.NewBuffer(body),
    )
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    scanner := bufio.NewScanner(resp.Body)
    for scanner.Scan() {
        line := scanner.Text()
        if strings.HasPrefix(line, "data: ") {
            data := strings.TrimPrefix(line, "data: ")
            if data == "[DONE]" {
                break
            }

            var chunk map[string]interface{}
            if err := json.Unmarshal([]byte(data), &chunk); err != nil {
                continue
            }

            if choices, ok := chunk["choices"].([]interface{}); ok && len(choices) > 0 {
                if choice, ok := choices[0].(map[string]interface{}); ok {
                    if delta, ok := choice["delta"].(map[string]interface{}); ok {
                        if content, ok := delta["content"].(string); ok {
                            fmt.Print(content)
                        }
                    }
                }
            }
        }
    }
    fmt.Println()
    return nil
}

func main() {
    chat("帮我推荐城阳区的Java开发岗位")
}
```

---

### 8.5 Vue.js 前端示例

```vue
<template>
  <div class="chat-container">
    <div class="messages">
      <div v-for="msg in messages" :key="msg.id" :class="['message', msg.role]">
        <div class="content" v-html="formatContent(msg.content)"></div>
      </div>
      <div v-if="loading" class="message assistant">
        <div class="content">{{ currentResponse }}</div>
      </div>
    </div>
    
    <div class="input-area">
      <input 
        v-model="input" 
        @keyup.enter="sendMessage"
        placeholder="输入消息..."
        :disabled="loading"
      />
      <button @click="sendMessage" :disabled="loading">发送</button>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const messages = ref([]);
const input = ref('');
const loading = ref(false);
const currentResponse = ref('');

async function sendMessage() {
  if (!input.value.trim() || loading.value) return;
  
  const userMessage = input.value;
  messages.value.push({
    id: Date.now(),
    role: 'user',
    content: userMessage
  });
  input.value = '';
  loading.value = true;
  currentResponse.value = '';
  
  try {
    const response = await fetch('http://localhost:8080/v1/chat/completions', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        model: 'qd-job-turbo',
        messages: messages.value.map(m => ({
          role: m.role,
          content: m.content
        })),
        stream: true
      })
    });
    
    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      
      const text = decoder.decode(value);
      const lines = text.split('\n');
      
      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') continue;
          
          try {
            const chunk = JSON.parse(data);
            const content = chunk.choices[0]?.delta?.content;
            if (content) {
              currentResponse.value += content;
            }
          } catch (e) {}
        }
      }
    }
    
    messages.value.push({
      id: Date.now(),
      role: 'assistant',
      content: currentResponse.value
    });
  } catch (error) {
    console.error('Chat error:', error);
  } finally {
    loading.value = false;
    currentResponse.value = '';
  }
}

function formatContent(content) {
  // 解析 job-json 代码块
  return content.replace(
    /```\s*job-json\n([\s\S]*?)```/g,
    (_, json) => {
      try {
        const job = JSON.parse(json);
        return `<div class="job-card">
          <h3>${job.jobTitle}</h3>
          <p class="company">${job.companyName}</p>
          <p class="salary">${job.salary}</p>
          <p class="info">${job.location} | ${job.education} | ${job.experience}</p>
          <a href="${job.appJobUrl}" target="_blank">查看详情</a>
        </div>`;
      } catch {
        return json;
      }
    }
  );
}
</script>

<style scoped>
.chat-container {
  max-width: 800px;
  margin: 0 auto;
  padding: 20px;
}

.messages {
  height: 500px;
  overflow-y: auto;
  border: 1px solid #ddd;
  padding: 10px;
  margin-bottom: 10px;
}

.message {
  margin-bottom: 10px;
  padding: 10px;
  border-radius: 8px;
}

.message.user {
  background: #e3f2fd;
  text-align: right;
}

.message.assistant {
  background: #f5f5f5;
}

.input-area {
  display: flex;
  gap: 10px;
}

.input-area input {
  flex: 1;
  padding: 10px;
  border: 1px solid #ddd;
  border-radius: 4px;
}

.input-area button {
  padding: 10px 20px;
  background: #1976d2;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.job-card {
  background: white;
  border: 1px solid #e0e0e0;
  border-radius: 8px;
  padding: 15px;
  margin: 10px 0;
}

.job-card h3 {
  margin: 0 0 8px 0;
  color: #1976d2;
}

.job-card .company {
  font-weight: bold;
  color: #333;
}

.job-card .salary {
  color: #e53935;
  font-size: 1.1em;
}

.job-card .info {
  color: #666;
  font-size: 0.9em;
}

.job-card a {
  display: inline-block;
  margin-top: 10px;
  color: #1976d2;
}
</style>
```

---

## 9. 错误处理

### 9.1 错误响应格式

```json
{
  "error": {
    "message": "错误描述信息",
    "type": "错误类型",
    "code": "错误代码"
  }
}
```

### 9.2 常见错误码

| HTTP 状态码 | 错误类型 | 说明 |
|------------|---------|------|
| 400 | `invalid_request` | 请求格式错误 |
| 400 | `multipart_parse_error` | multipart 表单解析失败 |
| 400 | `file_processing_error` | 文件处理失败 |
| 429 | `rate_limit_exceeded` | 请求过于频繁 |
| 500 | `internal_error` | 服务器内部错误 |

### 9.3 错误处理建议

```python
import requests

def safe_chat(message: str) -> str:
    try:
        response = requests.post(
            "http://localhost:8080/v1/chat/completions",
            json={
                "model": "qd-job-turbo",
                "messages": [{"role": "user", "content": message}],
                "stream": False
            },
            timeout=120
        )
        
        if response.status_code == 429:
            # 限流，等待后重试
            import time
            time.sleep(2)
            return safe_chat(message)
        
        response.raise_for_status()
        return response.json()["choices"][0]["message"]["content"]
        
    except requests.exceptions.Timeout:
        return "请求超时，请稍后重试"
    except requests.exceptions.RequestException as e:
        return f"请求失败: {e}"
```

---

## 10. 配置参考

### 10.1 完整配置文件 (config.yaml)

```yaml
# 服务器配置
server:
  port: 8080                 # 服务端口
  host: "0.0.0.0"            # 监听地址
  read_timeout: 30s          # 读取请求超时
  write_timeout: 300s        # 写入响应超时（流式响应需要更长时间）

# LLM配置
llm:
  base_url: "https://api.openai.com/v1"  # LLM API地址
  api_key: "sk-xxx"                       # LLM API密钥
  model: "gpt-4o"                         # 默认模型
  timeout: 120s                           # 请求超时
  max_retries: 3                          # 最大重试次数

# 高德地图配置
amap:
  api_key: "your-amap-key"                # 高德地图API密钥
  base_url: "https://restapi.amap.com/v3" # 高德API地址
  timeout: 10s                            # 请求超时

# 岗位API配置
job_api:
  base_url: "https://job-api.example.com" # 岗位API地址
  timeout: 30s                            # 请求超时

# OCR服务配置（文件解析）
ocr:
  base_url: "https://your-ocr-api.example.com"  # OCR服务地址（外网）
  # base_url: "http://127.0.0.1:9001"     # OCR服务地址（内网）
  timeout: 120s                           # 请求超时

# 政策咨询配置
policy:
  base_url: "http://policy-api.example.com"  # 政策API地址
  login_name: "your_login_name"              # 登录用户名
  user_key: "your_user_key"                  # 用户密钥
  service_id: "your_service_id"              # 服务ID
  timeout: 60s                               # 请求超时

# 日志配置
logging:
  level: "info"       # 日志级别：debug, info, warn, error
  format: "json"      # 日志格式：json, text

# 性能配置
performance:
  max_goroutines: 10000         # 最大并发goroutine数
  goroutine_pool_size: 5000     # goroutine池大小
  task_queue_size: 10000        # 任务队列大小
  enable_pprof: true            # 启用pprof性能分析（设为 false 可关闭 /debug/pprof/*）
  enable_metrics: true          # 启用指标收集（设为 false 可关闭 /metrics 与指标中间件）
  gc_percent: 100               # GC触发百分比
```

### 10.2 环境变量覆盖

环境变量会自动覆盖配置文件中的值：

| 环境变量 | 配置项 |
|---------|--------|
| `SERVER_PORT` | server.port |
| `SERVER_HOST` | server.host |
| `LLM_API_KEY` | llm.api_key |
| `LLM_BASE_URL` | llm.base_url |
| `LLM_MODEL` | llm.model |
| `AMAP_API_KEY` | amap.api_key |
| `OCR_BASE_URL` | ocr.base_url |
| `JOB_API_BASE_URL` | job_api.base_url |
| `POLICY_BASE_URL` | policy.base_url |
| `POLICY_LOGIN_NAME` | policy.login_name |
| `POLICY_USER_KEY` | policy.user_key |
| `POLICY_SERVICE_ID` | policy.service_id |

---

## 11. 部署指南

### 11.1 Docker Compose 部署

```yaml
# docker-compose.yml
version: '3.8'

services:
  qd-sc-server:
    build: .
    ports:
      - "8080:8080"
    environment:
      - LLM_API_KEY=sk-xxx
      - LLM_BASE_URL=https://api.openai.com/v1
      - AMAP_API_KEY=your-amap-key
      - OCR_BASE_URL=https://your-ocr-api.example.com
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

### 11.2 Kubernetes 部署

```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: qd-sc-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: qd-sc-server
  template:
    metadata:
      labels:
        app: qd-sc-server
    spec:
      containers:
      - name: qd-sc-server
        image: qd-sc-server:latest
        ports:
        - containerPort: 8080
        env:
        - name: LLM_API_KEY
          valueFrom:
            secretKeyRef:
              name: qd-sc-secrets
              key: llm-api-key
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: qd-sc-server
spec:
  selector:
    app: qd-sc-server
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer
```

### 11.3 Nginx 反向代理

```nginx
upstream qd_sc_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://qd_sc_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # SSE 支持
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding off;
        
        # 超时配置
        proxy_connect_timeout 60s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }
    
    # 文件上传大小限制
    client_max_body_size 20M;
}
```

---

## 12. 常见问题

### Q1: 如何处理流式响应中的岗位数据？

岗位数据会以特殊的 ```` ``` job-json ```` 代码块格式返回。客户端需要解析这个格式：

```javascript
function parseJobCards(content) {
  const jobRegex = /```\s*job-json\n([\s\S]*?)```/g;
  const jobs = [];
  let match;
  
  while ((match = jobRegex.exec(content)) !== null) {
    try {
      jobs.push(JSON.parse(match[1]));
    } catch (e) {}
  }
  
  return jobs;
}
```

### Q2: 流式响应中途断开怎么办？

建议实现重连机制：

```python
import time

def chat_with_retry(message, max_retries=3):
    for i in range(max_retries):
        try:
            return chat_stream(message)
        except Exception as e:
            if i < max_retries - 1:
                time.sleep(2 ** i)  # 指数退避
            else:
                raise e
```

### Q3: 如何实现多轮对话？

保存历史消息并在每次请求中传递：

```python
conversation = []

def chat(user_input):
    conversation.append({"role": "user", "content": user_input})
    
    response = client.chat.completions.create(
        model="qd-job-turbo",
        messages=conversation,
        stream=True
    )
    
    assistant_message = ""
    for chunk in response:
        content = chunk.choices[0].delta.content or ""
        assistant_message += content
        print(content, end="", flush=True)
    
    conversation.append({"role": "assistant", "content": assistant_message})
    print()
```

### Q4: 429 错误（限流）如何处理？

系统默认限流为：桶容量 200，每秒补充 50 个令牌。建议：
1. 实现请求重试机制，遇到 429 后等待 1-2 秒重试
2. 控制客户端的请求频率
3. 如需更高 QPS，联系管理员调整配置

### Q5: 如何调试 API 问题？

1. 启用 debug 日志级别
2. （可选）使用 `/metrics` 端点查看性能指标（需启用 `performance.enable_metrics`）
3. （可选）使用 `/debug/pprof/` 进行性能分析（需启用 `performance.enable_pprof`）
4. 检查服务器日志输出

---

## 附录

### A. 响应时间参考

| 操作 | 预期响应时间 |
|------|-------------|
| 健康检查 | < 10ms |
| 简单对话 | 2-5s |
| 岗位查询 | 3-8s |
| 文件解析 | 5-30s |
| 政策咨询 | 3-10s |

### B. 并发能力

| 指标 | 参考值 |
|------|--------|
| 最大并发连接 | 10,000 |
| 建议 QPS | 50 |
| 最大文件上传 | 10MB |

### C. 更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2025-11 | 初始版本 |