# llmage 模块开发文档

## 模块概述

llmage (LLM Manager & Engine) 是 Hermes Agent 平台的**大语言模型管理与推理模块**，负责 LLM 的全生命周期管理：模型注册、分类展示、推理调度、用量追踪与计费。

与 uapi 模块的配合关系：**llmage 负责模型的业务层**（模型目录、展示、推理调度、计费），**uapi 负责配置层的 API 对接**（将第三方 LLM API 配置为可调用的端点）。llmage 中的每个模型（llm 表记录）通过 `upappid` + `apiname` 关联到 uapi 的 API 配置，从而实现零代码接入新模型。

核心职责：
- 模型管理：模型注册、分类（catelog）、供应商（provider）管理
- 推理引擎：流式/同步/异步三种推理模式，自动路由
- 用量追踪：每次调用记录 token 用量、响应时间、用户信息
- 计费系统：按定价程序（pricing program）计算费用，后台异步记账
- 前端展示：按目录/供应商分类展示模型卡片，点击即推理对话
- 异步任务：视频生成等长任务的提交、轮询、状态查询

---

## 目录结构

```
llmage/
├── pyproject.toml              # 构建配置
├── llmage/                     # Python 源码包
│   ├── __init__.py             # 空
│   ├── init.py                 # 模块初始化，注册函数到 ServerEnv + 后台记账任务
│   ├── llmclient.py            # 推理引擎核心：uapi_request / sync_uapi_request / async_uapi_request
│   ├── syncinference.py        # 同步推理模式
│   ├── asyncinference.py       # 异步推理模式 + 任务状态轮询
│   ├── accounting.py           # 计费与记账：余额检查、充电、后台异步记账
│   ├── utils.py                # 工具函数：BufferedLLMs 缓存、查询订单、价格计算等
│   ├── callback.py             # 回调处理
│   ├── messages.py             # 消息格式化
│   ├── keling.py               # 可灵（Keling）视频模型 token 管理
│   └── jimeng.py               # 即梦（Jimeng）图像模型认证
├── models/                     # 表定义（xlsx 格式）
│   ├── llm.xlsx                # 模型定义
│   ├── llmusage.xlsx           # 模型调用记录
│   ├── llmcatelog.xlsx         # 模型目录
│   └── historyformat.xlsx      # 历史对话格式
├── wwwroot/                    # Web 前端资源
│   ├── menu.ui                 # 菜单
│   ├── show_llms.ui            # 按目录展示模型卡片
│   ├── show_llms_by_providers.ui  # 按供应商展示模型
│   ├── show_same_catelog_llm.ui   # 同目录模型展示
│   ├── llm_dialog.ui           # 模型对话窗口（LlmIO 控件）
│   ├── llminference.dspy       # 推理入口（调用 inference_generator）
│   ├── list_paging_catelog_llms.dspy  # 分页目录模型列表
│   ├── list_catelog_models.dspy     # 目录模型列表
│   ├── get_type_llms.dspy      # 按类型获取模型
│   ├── model_estimate.dspy     # 费用预估
│   ├── query_price.dspy        # 价格查询
│   ├── llmcost.dspy            # 费用统计
│   ├── llmcheck.dspy           # 模型检查
│   ├── llmaccounting.dspy      # 手动记账触发
│   ├── vidu_inference.dspy     # Vidu 视频推理入口
│   ├── vidu_callback.dspy      # Vidu 回调处理
│   ├── get_asynctask_status.dspy    # 异步任务状态查询
│   ├── get_my_asynctasks.dspy       # 我的异步任务列表
│   ├── grap_task_status.dspy        # 抓取任务状态
│   ├── tasks/index.dspy        # 任务管理入口
│   ├── openai/index.dspy       # OpenAI 兼容接口
│   ├── v1/chat/completions/index.dspy  # OpenAI v1 聊天接口
│   ├── t2t/index.dspy          # 文本到文本接口
│   └── video/index.dspy        # 视频生成接口
└── script/
    └── perms.json              # RBAC 权限配置
```

---

## 数据库表结构

### 表关系

```
llmcatelog (模型目录) ──1:N──> llm (模型)
llm (模型) ──N:1──> upapp (上位系统, 通过 uapi 模块)
llm (模型) ──1:N──> llmusage (调用记录)
```

### 核心表说明

| 表名 | 说明 | 关键字段 |
|------|------|----------|
| **llmcatelog** | 模型目录分类 | id, name |
| **llm** | 模型定义 | id, name, model, providerid, ownerid, upappid, apiname, llmcatelogid, stream（同步/异步/流式）, ppid（定价程序id）, callbackurl, enabled_date, expired_date, input_fields |
| **llmusage** | 模型调用记录 | id, llmid, userid, userorgid, usages(token用量), status(SUCCEEDED/FAILED), amount(金额), cost(成本), use_time, accounting_status(created/accounted/failed), taskid(异步任务id) |
| **historyformat** | 历史对话格式 | id, name, format |

---

## 架构设计：llmage + uapi 协同

```
用户点击模型卡片
       │
       ▼
  llm_dialog.ui ── 显示 LlmIO 对话控件
       │
       ▼
  llminference.dspy ── 推理入口
       │
       ▼
  inference_generator() ── 推理引擎核心（llmclient.py）
       │
       ├── 判断 llm.stream:
       │
       ├── 'async' ──→ async_uapi_request() ── 提交任务 + 后台轮询状态
       │                     │
       │                     └── 通过 uapi 的 UpAppApi 调用远端 API
       │
       ├── False ──→ sync_uapi_request() ─── 一次性同步调用
       │                     │
       │                     └── 通过 uapi 的 UpAppApi 调用远端 API
       │
       └── True ──→ uapi_request() ────── 流式调用（SSE）
                             │
                             └── 通过 uapi 的 UpAppApi stream_linify()
```

**关键连接点**：llm 表中的 `upappid` + `apiname` 指向 uapi 模块中配置的外部 API。uapi 负责：
- 管理 upapp（上位系统）的 baseurl、认证密钥
- 管理 uapi（API 定义）的 httpmethod、path、headers、模板渲染
- 提供 UpAppApi 类进行实际 HTTP 调用

llmage 负责：
- 模型业务逻辑（分类、展示、选择）
- 推理调度（选择同步/异步/流式模式）
- 调用记录追踪（llmusage 表）
- 计费记账（accounting）

---

## Python API

### 模块初始化

```python
def load_llmage():
    env = ServerEnv()
    env.llm_query_orders = llm_query_orders
    env.read_webpath = read_webpath
    env.get_llm_by_model = get_llm_by_model
    env.llm_charging = llm_charging
    env.get_accounting_llmusages = get_accounting_llmusages
    env.llm_accounting = llm_accounting
    env.get_today_asynctask_list = get_today_asynctask_list
    env.get_asynctask_status = get_asynctask_status
    env.query_task_status = query_task_status
    env.get_llm = get_llm
    env.inference = inference
    env.inference_generator = inference_generator
    env.get_llms_by_catelog = get_llms_by_catelog
    env.get_llmcatelogs = get_llmcatelogs
    env.checkCustomerBalance = checkCustomerBalance
    env.get_llmproviders = get_llmproviders
    env.get_llms_sort_by_provider = get_llms_sort_by_provider
    env.keling_token = keling_token
    env.llm_query_price = llm_query_price
    env.jimeng_auth_headers = jimeng_auth_headers

    # 启动后台记账任务
    add_cleanupctx(start_backend)  # backend_accounting() 每10秒轮询
```

其他模块的 `.dspy` 文件可通过 `globals()` 直接使用这些函数。

### 推理引擎（llmclient.py）

三种推理模式：

#### 1. 流式推理（uapi_request）

适用于支持 SSE 流式返回的 LLM API（如 GPT-4、Claude）。

```python
async for line in uapi_request(request, llm, callerid, callerorgid, params_kw):
    yield line  # 每行是一个 JSON，包含 content/reasoning_content/usage
```

**输出格式**：
```json
{"content": "你好", "llmusageid": "xxx"}
{"reasoning_content": "让我想想...", "llmusageid": "xxx"}
{"usage": {"prompt_tokens": 10, "completion_tokens": 20}, "llmusageid": "xxx"}
```

#### 2. 同步推理（sync_uapi_request）

适用于一次性返回完整结果的 API。

```python
result = await sync_uapi_request(request, llm, callerid, callerorgid, params_kw)
# result 是 JSON 字符串
```

#### 3. 异步推理（async_uapi_request）

适用于视频生成等耗时任务。提交后立即返回 taskid，后台轮询状态。

```python
result = await async_uapi_request(request, llm, callerid, callerorgid, params_kw)
# result: {"taskid": "xxx", "status": "PENDING"}
# 后台自动通过 query_task_status() 轮询，更新 llmusage 表
```

### inference / inference_generator 入口

```python
# 在 .dspy 中使用（流式）
async def handle(request, params_kw=None):
    async for line in inference_generator(request, params_kw=params_kw):
        yield line

# 或者直接使用 inference（自动包装为流式响应）
result = await inference(request, params_kw=params_kw)
```

**参数要求**：
- `params_kw.llmid`: 模型 ID（必填）
- `params_kw.model`: 模型名称（可选，自动从 llm 表填充）
- `params_kw.transno`: 交易号（可选，自动生成）
- `params_kw.stream`: 是否流式（可选）

### 模型查询

```python
# 通过 llmid 获取模型信息（带内存缓存）
llm = await get_llm(llmid)

# 按目录获取模型列表
llms_by_catelog = await get_llms_by_catelog()
# 返回: [{'catelogid': 'x', 'catelogname': '文本', 'llms': [...]}]

# 按供应商获取模型列表
llms_by_provider = await get_llms_sort_by_provider()

# 获取所有目录
catelogs = await get_llmcatelogs()

# 获取所有供应商
providers = await get_llmproviders()
```

### 计费与记账（accounting.py）

```python
# 检查用户余额是否足够使用某模型
has_balance = await checkCustomerBalance(llmid, userorgid)

# 计算费用（通过定价程序）
chargings = await llm_charging(ppid, llmusage)
# 返回: DictObject(original_amount, amount, cost)

# 价格查询
prices = await llm_query_price(llmid, config_data)

# 后台记账（由 start_backend 自动启动，每10秒轮询）
# 处理 llmusage 中 accounting_status='created' 的记录
await backend_accounting()

# 手动记账
await llm_accounting(llmusage)
```

### 异步任务管理（asyncinference.py）

```python
# 查询异步任务状态
status = await get_asynctask_status(request, taskid)
# 返回: {'taskid': 'xxx', 'status': 'SUCCEEDED'|'FAILED'|'PENDING', ...}

# 获取今天的异步任务列表
tasks = await get_today_asynctask_list(userid)

# 手动轮询任务状态（onetime=True 只查一次）
await query_task_status(request, luid, onetime=False)
```

---

## 前端页面

### show_llms.ui — 模型展示

按目录（catelog）分组展示模型卡片，点击卡片弹出 llm_dialog.ui 对话窗口。

```jinja2
{% for cate in get_llms_by_catelog() %}
    {% for llm in cate.llms %}
        模型卡片 → click → urlwidget → llm_dialog.ui?id={{llm.id}}
    {% endfor %}
{% endfor %}
```

### llm_dialog.ui — 模型对话窗口

LlmIO 控件，支持流式输出、多模型切换、知识库选择等。

```jinja2
{% if checkCustomerBalance(params_kw.id, userorgid) %}
{% set llm = get_llm(params_kw.id) %}
    LlmIO 控件 → 推理地址: /llmage/llminference.dspy
{% endif %}
```

### llminference.dspy — 推理入口

```python
# 接收 params_kw（包含 llmid、prompt 等参数）
# 调用 inference_generator 进行推理
async for line in inference_generator(request, params_kw=params_kw):
    yield line
```

### OpenAI 兼容接口

- `/llmage/openai/` — OpenAI 兼容的接口入口
- `/llmage/v1/chat/completions/` — 标准 OpenAI chat completions 接口

---

## 关键设计要点

1. **llm ↔ uapi 桥接**：llm 表通过 `upappid` + `apiname` 关联到 uapi 的 API 配置，实现零代码接入新模型
2. **BufferedLLMs 缓存**：模型定义按日期缓存，避免每次查询数据库；跨天自动失效
3. **三种推理模式**：流式（SSE）、同步（一次性返回）、异步（提交+轮询），根据 `llm.stream` 字段自动选择
4. **异步任务轮询**：后台自动轮询任务状态（`query_task_status`），支持多 API 名称轮询（`query_apiname` 逗号分隔）
5. **IO 持久化**：每次调用的输入输出以 JSON 文件存储（通过 FileStorage），llmusage 表只存 webpath
6. **计费延迟**：联机不调账，标记 `accounting_status='created'`，后台记账任务每10秒批量处理
7. **API Key 保护**：异常信息中的 Bearer token 会被 `erase_apikey()` 替换为 XXXXXXXX
8. **供应商认证**：可灵（keling_token）和即梦（jimeng_auth_headers）有专用的认证函数

---

## 依赖关系

```
llmage
├── sqlor          # 数据库 ORM
├── apppublic      # 工具库（日志、唯一ID、时间工具等）
├── ahserver       # Web 服务器框架
├── uapi           # 外部 API 网关（推理调用依赖 UpAppApi）
└── accounting     # 计费模块（consume_accounting, getCustomerBalance）
```

---

## 开发注意事项

1. **llm.stream 字段**：控制推理模式 — `'async'` 为异步任务、`False` 为同步、`True` 为流式
2. **llm 表关联链**：llm → upapp → uapiset → uapi + uapiio，新增模型需在 uapi 模块中先配置好 API 定义
3. **input_fields**：模型的输入字段定义存储在 uapiio 表中，BufferedLLMs 加载时自动关联
4. **计费开关**：目前联机不调账（代码中已注释），所有 amount/cost 为 0，由后台任务统一处理
5. **异步任务 query_apiname**：支持多个 API 名称逗号分隔，逐个轮询直到状态变为 SUCCEEDED/FAILED
6. **query_period**：轮询间隔（秒），默认 30 秒，在 llm 表中配置