# EasyLink Fin-Chat 金融投研知识问答

## 概述

Fin-Chat 是一个专注于金融投研领域的知识问答模型，基于海量金融文档构建。支持公司财报分析、行业研究、股价趋势等专业问题，响应内容附带原始文档引用（文件名、页码、访问链接），方便溯源核查。

接口采用 OpenAI Chat Completions 兼容格式，支持流式和非流式两种响应方式，可直接使用 OpenAI SDK 接入。

更多细节请参考 [EasyLink 官方文档](https://docs.easylink-ai.com/docs/capabilities/qa/api)。

**请求地址**：`https://api.modelverse.cn/v1/chat/completions`

## 支持模型

- `easydoc-fin-chat`

## 请求参数

| 字段 | 类型 | 是否必需 | 说明 |
| :--- | :--- | :--- | :--- |
| model | string | 是 | 模型名称，固定为 `easydoc-fin-chat` |
| messages | array | 是 | 对话消息数组，支持 `user` / `assistant` / `system` |
| stream | boolean | 否 | 是否启用流式返回，默认 `false` |
| temperature | float | 否 | 温度参数，范围 0-2，默认 1 |
| max_tokens | integer | 否 | 最大生成 token 数 |

## 响应字段

### 非流式响应

| 字段 | 类型 | 说明 |
| :--- | :--- | :--- |
| choices[0].message.content | string | 生成的回答文本 |
| choices[0].message.annotations | array | 文档引用列表，见下方说明 |
| choices[0].finish_reason | string | 完成原因：`stop` / `length` |
| usage.prompt_tokens | integer | 输入 token 数 |
| usage.completion_tokens | integer | 输出 token 数 |
| usage.total_tokens | integer | 总 token 数 |

### 流式响应（SSE）

每条消息以 `data: ` 开头，流结束时发送 `data: [DONE]`。`delta` 对象字段与非流式 `message` 一致。

### annotations 文档引用

| 字段 | 类型 | 说明 |
| :--- | :--- | :--- |
| file_name | string | 来源文档文件名 |
| url | string | 文档访问链接（带签名，有时效性） |
| page_number | integer | 引用页码 |

## 示例

### Curl 示例

**非流式：**

```bash
curl -X POST https://api.modelverse.cn/v1/chat/completions \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "easydoc-fin-chat",
    "messages": [
      {"role": "user", "content": "比亚迪2024年Q3营收同比增长率？"}
    ]
  }'
```

**流式：**

```bash
curl -X POST https://api.modelverse.cn/v1/chat/completions \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "easydoc-fin-chat",
    "messages": [
      {"role": "user", "content": "比亚迪2024年Q3营收同比增长率？"}
    ],
    "stream": true
  }'
```

### Python 示例

```python
from openai import OpenAI

client = OpenAI(
    api_key="******",  # 替换为你的 API Key
    base_url="https://api.modelverse.cn/v1",
)

# 流式调用
response = client.chat.completions.create(
    model="easydoc-fin-chat",
    messages=[
        {"role": "user", "content": "比亚迪2024年Q3营收同比增长率？"}
    ],
    stream=True,
)

for chunk in response:
    delta = chunk.choices[0].delta

    # 处理文本内容
    if delta.content:
        print(delta.content, end="", flush=True)

    # 处理文档引用（自定义扩展字段）
    if hasattr(delta, "annotations") and delta.annotations:
        for annotation in delta.annotations:
            print(f"\n引用: {annotation['file_name']} 第 {annotation['page_number']} 页")
            print(f"链接: {annotation['url']}")
```

## 响应示例

**非流式响应：**

```json
{
  "id": "resp_xxxxxxxxxxxxxxxx",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "easydoc-fin-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "根据比亚迪2024年第三季度财报，营收为2011.25亿元，同比增长24.04%。",
        "annotations": [
          {
            "file_name": "比亚迪:2024年三季度报告.pdf",
            "url": "https://oss.easylink-ai.com/easylink-investplatform/file_md5/xxx.pdf?signature=...",
            "page_number": 2
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 128,
    "completion_tokens": 64,
    "total_tokens": 192
  }
}
```

## 使用说明

1. **OpenAI SDK 兼容**：将 `base_url` 设为 `https://api.modelverse.cn/v1`，`api_key` 设为你的 Modelverse API Key，即可直接使用 OpenAI SDK 调用。
2. **文档引用**：响应中的 `annotations` 是扩展字段，标准 OpenAI SDK 解析时需通过 `hasattr` 判断是否存在后再读取。
3. **引用链接时效**：`annotations[].url` 带签名参数，有有效期限制，请及时访问，不要长期存储。
4. **流式建议**：使用 cURL 测试流式响应时加 `--no-buffer` 参数，否则内容可能延迟输出。
5. **计费**：按 token 计费，用量通过 `usage.prompt_tokens` 和 `usage.completion_tokens` 返回。