Metadata-Version: 2.4
Name: xiaothink
Version: 1.4.9
Summary: An AI toolkit that helps users quickly call interfaces related to the Xiaothink framework.
Author: Shi Jingqi
Author-email: xiaothink@foxmail.com
License: Apache License 2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.21.0
Requires-Dist: requests>=2.25.0
Provides-Extra: tensorflow
Requires-Dist: tensorflow>=2.10.0; extra == "tensorflow"
Provides-Extra: paddle
Requires-Dist: paddlepaddle>=2.5.0; extra == "paddle"
Requires-Dist: jieba>=0.42.1; extra == "paddle"
Provides-Extra: paddle-gpu
Requires-Dist: paddlepaddle-gpu>=2.5.0; extra == "paddle-gpu"
Requires-Dist: jieba>=0.42.1; extra == "paddle-gpu"
Provides-Extra: torch
Requires-Dist: torch>=2.0.0; extra == "torch"
Provides-Extra: vision
Requires-Dist: Pillow>=9.0.0; extra == "vision"
Provides-Extra: server
Requires-Dist: flask>=2.0.0; extra == "server"
Provides-Extra: all
Requires-Dist: tensorflow>=2.10.0; extra == "all"
Requires-Dist: paddlepaddle>=2.5.0; extra == "all"
Requires-Dist: jieba>=0.42.1; extra == "all"
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: Pillow>=9.0.0; extra == "all"
Requires-Dist: flask>=2.0.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Xiaothink Python 模块使用文档

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
Xiaothink 是一个以自然语言处理（NLP）为核心的AI研究组织，致力于在少数据、低算力下训练出先进的端侧模型。Xiaothink Python 模块是我们提供的核心工具包，涵盖了文本问答、图文问答、图像压缩、情感分类等多种功能。以下是详细的使用指南和代码示例。

## 目录

1. [安装](#安装)
2. [License](#license)
3. [本地纯文本对话模型](#本地纯文本对话模型)
4. [基于 PaddlePaddle 的模型（v1.4.0 新增）](#基于-paddlepaddle-的模型v140-新增)
5. [基于 PyTorch 的模型（T17，v1.4.2 新增）](#基于-pytorch-的模型t17v142-新增)
   - [翻译功能](#翻译功能pytorch)
   - [小说角色扮演（v1.4.4 新增）](#小说角色扮演torchnovelmodelv144-新增)
6. [图像特征提取与多模态对话](#图像特征提取与多模态对话)
7. [图像压缩转特征技术 (img\_zip)](#图像压缩转特征技术-img_zip)
8. [情感分类工具](#情感分类工具)
9. [AI率检测工具](#AI率检测工具)
10. [TinySkill 工具箱（v1.4.2 新增）](#tinyskill-工具箱v142-新增)
11. [ImgTok 视觉支持（v1.4.3 新增）](#imgtok-视觉支持v143-新增)
12. [图像压缩第二代（img\_zip2，v1.4.5 新增）](#图像压缩第二代img_zip2v145-新增)
13. [OpenAI 兼容服务器与网页聊天（v1.4.7 新增）](#openai-兼容服务器与网页聊天v147-新增)
14. [小思框架系列模型名称](#-小思框架系列模型名称)
15. [更新日志](#更新日志)

***

## 安装

首先，您需要通过 pip 安装 Xiaothink 模块：

```bash
pip install xiaothink          # 基础安装（无深度学习后端）
pip install xiaothink[torch]   # 包含 PyTorch（T17 推荐）
pip install xiaothink[all]     # 包含所有后端
```

### 后端控制（环境变量 v1.4.2 新增）

通过设置 `XIAOTHINK_BACKEND` 环境变量，可控制本库只导入指定的深度学习后端，避免未使用的后端带来兼容性问题（如 numpy 2.0 导致 TensorFlow 崩溃）。

**用法**（在运行 Python 脚本前设置）：

| 命令                                           | 效果                          |
| -------------------------------------------- | --------------------------- |
| `set XIAOTHINK_BACKEND=torch` (Windows)      | 只导入 PyTorch（T17 用户推荐）       |
| `set XIAOTHINK_BACKEND=paddle` (Windows)     | 只导入 PaddlePaddle（T7.5 用户推荐） |
| `set XIAOTHINK_BACKEND=tensorflow` (Windows) | 只导入 TensorFlow（T7 及以下用户推荐）  |
| 不设置或 `auto`                                  | 尝试导入所有后端（默认）                |

**示例（Windows PowerShell）**：

```powershell
# 只使用 PyTorch，完全跳过 TensorFlow 和 PaddlePaddle
$env:XIAOTHINK_BACKEND='torch'
python your_script.py
```

**示例（Linux/Mac）**：

```bash
# 只使用 PyTorch，完全跳过 TensorFlow 和 PaddlePaddle
export XIAOTHINK_BACKEND=torch
python your_script.py
```

> **提示**：如果你的环境同时安装了多个深度学习框架但只用其中一个，建议设置此环境变量以加快导入速度并避免兼容性问题。

***

## License

This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details.

The [NOTICE](NOTICE) file contains additional attribution information for the proprietary technologies included in this module.

***

## 本地纯文本对话模型

对于本地加载的对话模型，根据模型类型的不同，应调用相应的函数来进行对话。

### 单轮对话（即将在未来版本被移除）

适用于单轮对话场景。

### 示例代码

```python
import xiaothink.llm.inference.test_formal as tf

model = tf.QianyanModel(
    ckpt_dir=r'path/to/your/t6_model',
    MT='t6_beta_dense',
    vocab=r'path/to/your/vocab'# vocab文件在模型储存库中已给出
)

while True:
    inp = input('【问】：')
    if inp == '[CLEAN]':
        print('【清空上下文】\n\n')
        model.clean_his()
        continue
    re = model.chat_SingleTurn(inp, temp=0.32)  # 使用 chat_SingleTurn 进行单轮对话
    print('\n【答】：', re, '\n')
```

### 多轮对话

适用于多轮对话场景。

### 示例代码

```python
import xiaothink.llm.inference.test_formal as tf

model = tf.QianyanModel(
    ckpt_dir=r'path/to/your/t6_model',
    MT='t6_beta_dense',
    vocab=r'path/to/your/vocab'# vocab文件在模型储存库中已给出
)

while True:
    inp = input('【问】：')
    if inp == '[CLEAN]':
        print('【清空上下文】\n\n')
        model.clean_his()
        continue
    re = model.chat(inp, temp=0.32)  # 使用 chat 进行多轮对话
    print('\n【答】：', re, '\n')
```

### 手动添加历史对话

使用 `add_his` 方法可以手动添加历史对话记录，适用于预设对话上下文的场景。

```python
import xiaothink.llm.inference.test_formal as tf

model = tf.QianyanModel(
    ckpt_dir=r'path/to/your/t6_model',
    MT='t6_beta_dense',
    vocab=r'path/to/your/vocab'
)

# 手动添加历史对话
model.add_his('你叫什么名字？', '我的名字是"小思"，很高兴认识你！')
model.add_his('你好，小思', '你也好呀！')

# 后续对话会基于已添加的历史上下文
while True:
    inp = input('【问】：')
    if inp == '[CLEAN]':
        print('【清空上下文】\n\n')
        model.clean_his()
        continue
    re = model.chat(inp, temp=0.32)
    print('\n【答】：', re, '\n')
```

**注意**：

- `add_his(q, a, form)` 方法接受三个参数：问题 `q`、回答 `a` 和格式 `form`
- T6 系列模型默认 `form=1`（指令微调模型），预训练模型使用 `form='pretrain'`
- T7.5 系列模型使用 `form=2`
- T17 系列模型（PyTorch）不需要 `form` 参数

### 文本续写

适用于更灵活的文本续写场景

### 示例代码

```python
import xiaothink.llm.inference.test as test

MT = 't6_beta_dense'
m, d = test.load(
    ckpt_dir=r'path/to/your/t6_model',
    MT='t6_beta_dense',
    vocab=r'path/to/your/vocab'# vocab文件在模型储存库中已给出
)

inp='你好！'
belle_chat = '{"conversations": [{"role": "user", "content": {inp}}, {"role": "assistant", "content": "'.replace('{inp}', inp)    # t6系列中经过指令微调的模型支持的instruct格式
inp_m = belle_chat

ret = test.generate_texts_loop(m, d, inp_m,    
                               num_generate=100,
                               every=lambda a: print(a, end='', flush=True),
                               temperature=0.32,
                               pass_char=['▩'])    #▩是t6系列模型的<unk>标识
```

**重要提示**：对于本地模型，建议调用 `model.chat` 函数进行多轮对话，未进行指令微调的预训练模型建议调用 `test.generate_texts_loop` 函数。\*\* 单轮对话的 `model.chat_SingleTurn` 函数即将在未来版本被移除 \*\*

***

## 基于 PaddlePaddle 的模型（v1.4.0 新增）

Xiaothink 现已支持基于 PaddlePaddle 的 RWKV 架构模型。这些模型提供高效的推理能力，适合资源受限的环境。

### 安装

```bash
pip install xiaothink
pip install paddlepaddle  # 或 paddlepaddle-gpu 用于 GPU 支持
```

### 多轮对话（PaddlePaddle）

```python
from xiaothink.llm.inference_paddle import QianyanModel

model = QianyanModel(
    ckpt_dir=r'path/to/your/t7.5_model',
    MT='t7.5_paddle_small_instruct_pro'
)

while True:
    inp = input('[问]: ')
    if inp == '[CLEAN]':
        print('[清空上下文]\n\n')
        model.clean_his()
        continue
    re = model.chat(inp, temp=0.34, form=2)  # form=2 为简化格式
    print('\n[答]:', re, '\n')
```

### 文本生成（PaddlePaddle）

```python
from xiaothink.llm.inference_paddle import TextGenerator

generator = TextGenerator(
    checkpoint_path=r'path/to/your/t7.5_model',
    MT='t7.5_paddle_small_instruct_pro'
)
generator.load_model()

generated_text = generator.generate_text(
    prompt='<|U|>你好，最近怎么样？<|A|>',
    max_length=100,
    temperature=0.8,
    top_p=0.9,
    repetition_penalty=1.2
)
print(generated_text)
```

### 支持的模型架构（PaddlePaddle）

| 模型名称                           | MT 参数                                       | 描述     |
| ------------------------------ | ------------------------------------------- | ------ |
| Xiaothink-T7.5-0.1B            | 't7.5\_paddle\_small\_instruct'             | 基础指令模型 |
| Xiaothink-T7.5-0.1B-Pro        | 't7.5\_paddle\_small\_instruct\_pro'        | 增强指令模型 |
| Xiaothink-T7.5-0.1B-Thinking   | 't7.5\_paddle\_small\_instruct\_thinking'   | 思维链模型  |
| Xiaothink-T7.5-0.1B-Poem       | 't7.5\_paddle\_small\_instruct\_poem'       | 诗歌生成模型 |
| Xiaothink-T7.5-0.1B-Translator | 't7.5\_paddle\_small\_instruct\_translator' | 翻译模型   |

### 自动设备选择

PaddlePaddle 模块会根据 GPU 内存使用率自动选择最优设备：

```python
# 自动设备选择（默认）
# 如果 GPU 内存使用率 > 80%，则切换到 CPU
AUTO_DEVICE = True
GPU_MEMORY_THRESHOLD = 80.0

# 或手动设置设备
import paddle
paddle.set_device('cpu')  # 或 'gpu:0'
```

### Train-On-Time (TOT) 动态学习

Xiaothink 提供了创新的 Train-On-Time (TOT) 功能，支持推理时动态学习。与传统模型不同，TOT 模型会从你的训练数据仓库中持续学习相似示例，实现实时知识更新。

**TOT 工作原理：**

1. **相似度匹配**：自动从训练数据中找到相似的指令
2. **动态微调**：使用这些相似示例在内存中微调模型
3. **增强响应**：基于新学习的知识生成更准确的答案
4. **内存管理**：优化 GPU 内存使用并清理资源

**核心特性：**

- **实时学习**：每次对话都会从相关示例中学习
- **基于相似度匹配**：使用 difflib 查找语义相似的指令
- **并行处理**：多核心相似度计算，匹配速度更快
- **多格式支持**：加载各种检查点格式的模型
- **GPU 优化**：自动 GPU 内存管理

```python
from xiaothink.llm.inference_paddle import TOTModel, TOT_AVAILABLE

if TOT_AVAILABLE:
    # 自定义训练数据路径
    custom_data_paths = [
        r'path/to/your/belle_train.jsonl',
        r'path/to/your/coig_minimind.jsonl',
        r'path/to/your/firefly_data.jsonl'
    ]
    
    model = TOTModel(
        ckpt_dir=r'path/to/your/t7.5_model',
        MT='t7.5_paddle_small_instruct_pro',
        data_paths=custom_data_paths  # 自定义训练数据路径
    )
    
    # 模型会在回答前自动从相似示例中学习
    while True:
        inp = input('[问]: ')
        if inp == '[CLEAN]':
            model.clean_his()
            continue
        re = model.chat(inp, temp=0.68)
        print('\n[答]:', re, '\n')
else:
    print("TOT 功能需要 PaddlePaddle 支持")
```

**自定义数据路径：**
您现在可以在初始化 TOTModel 时指定自己的训练数据路径：

```python
# 默认行为（使用内置路径）
model = TOTModel(ckpt_dir='path/to/model')

# 自定义数据路径
model = TOTModel(
    ckpt_dir='path/to/model',
    data_paths=[
        'path/to/data1.jsonl',
        'path/to/data2.jsonl',
        'path/to/data3.txt'
    ]
)
```

**训练数据要求：**
TOT 会在以下位置查找训练数据：

1. `belle_train_3.5M_CN_minimindtype.jsonl`
2. `coig_minimind.jsonl`
3. `minimindtype_firefly_1_1M.jsonl`
4. 各种指令格式文件
5. 诗歌和翻译数据

**内存优化：**

- 自动 GPU 内存清理
- 内存中微调，无需磁盘写入
- 批处理实现高效训练

***

## 支持的文件格式

TOT 系统支持以下文件格式：

- .jsonl 文件（JSON Lines 格式）
- .txt 文件（文本文件）

## 支持的数据结构
系统能够识别和处理两种主要的数据结构：

### 1. 对话格式（Conversations Format）
```json
{
  "conversations": [
    {"content": "User question"},
    {"content": "Assistant answer"}
  ]
}
```

### 2. 指令-输出格式（Instruction-Output Format）
```json
{
  "instruction": "Instruction content",
  "output": "Output content"
}
```

**内存优化：**
- 自动 GPU 内存清理
- 内存中微调，无需磁盘写入
- 批处理实现高效训练

***

## 基于 PyTorch 的模型（T17，v1.4.2 新增）

Xiaothink 现已支持基于 PyTorch 的 GRU/LSTM 架构模型，具有创新的历史检索机制。这些模型专为高效的端侧推理设计，具有创新的历史感知能力。

### 安装

```bash
pip install xiaothink
pip install torch  # T17 模型需要 PyTorch
```

### 多轮对话（PyTorch）

```python
from xiaothink.llm.inference_torch.torch_formal import TorchModel

model = TorchModel(
    ckpt_dir=r'path/to/your/t17_model',
    MT='t17_tiny'
)

while True:
    inp = input('[问]: ')
    if inp == '[CLEAN]':
        print('[清空上下文]\n\n')
        model.clean_his()
        continue
    re = model.chat(inp, temperature=0.7, top_p=0.9)
    print('\n[答]:', re, '\n')
```

### 文本生成（PyTorch）

```python
from xiaothink.llm.inference_torch.torch_test import TextGenerator

generator = TextGenerator(
    checkpoint_path=r'path/to/your/t17_model',
    MT='t17_tiny'
)
generator.load_model()

generated_text = generator.generate_text(
    prompt='<s>你好，请介绍一下自己。',
    max_length=128,
    temperature=0.7,
    top_p=0.9
)
print(generated_text)
```

### 支持的模型架构（PyTorch）

| 模型名称                             | MT 参数                       | 描述                                                           |
| -------------------------------- | --------------------------- | ------------------------------------------------------------ |
| Xiaothink-T17-Tiny               | 't17\_tiny'                 | 基于 GRU3 的历史检索模型（d\_model=450, num\_layers=14）                |
| Xiaothink-T17-Tiny-Novel         | 't17\_tiny\_novel'          | 长文本历史检索模型（d\_model=768, max\_seq\_len=10000）                 |
| Xiaothink-T17-RWKV5-MLA          | 't17\_rwkv5\_mla'           | RWKV-v5 + MLA 纯历史检索模型（d\_model=1400, num\_layers=16）（v1.4.8） |
| Xiaothink-T17-RWKV5-MLA-Instruct | 't17\_rwkv5\_mla\_instruct' | t17\_rwkv5\_mla 指令微调版（v1.4.8）                                |

### 核心特性

- **历史检索**：创新的历史上下文检索机制，生成时检索相关历史信息
- **高效推理**：针对端侧部署优化，内存占用低
- **门控融合**：可学习的门控机制，融合 RNN 输出与检索到的历史
- **因果掩码**：确保训练和推理时无未来信息泄露
- **ImgTok 视觉集成**（vision 模型）：自动处理 `<imgtoken>` 图像标签输入和 ImgTok 输出重建

### 翻译功能（PyTorch）

TorchModel 提供内置的 `translate()` 方法，支持英译中、中译英模式：

```python
from xiaothink.llm.inference_torch.torch_formal import TorchModel

model = TorchModel(ckpt_dir=r'path/to/your/t17_model', MT='t17_tiny')

# 英译中
result = model.translate("Hello, how are you?", mode="en2zh")
print(result)

# 中译英
result = model.translate("今天天气真好", mode="zh2en")
print(result)

# 自由翻译模式
result = model.translate("帮我翻译这段话", mode="free")
print(result)
```

### 小说角色扮演（TorchNovelModel，v1.4.4 新增）

`TorchNovelModel` 类继承自 `TorchModel`，专为小说角色扮演场景设计，支持多角色自动接话和故事背景设置。

```python
from xiaothink.llm.inference_torch.torch_novel import TorchNovelModel

# 初始化小说模型（推荐使用 vision 模型以获得 ImgTok 支持）
model = TorchNovelModel(
    ckpt_dir=r'path/to/your/t17_model',
    MT='t17_tiny_vision'
)

# 设置角色
model.set_model_name('顾言;林婉')     # 模型扮演的角色（多角色用 ; 分隔）
model.set_user_name('林婉')           # 用户扮演的角色
model.set_setting('夜黑风高的晚上，林婉正准备睡觉。')  # 故事背景

# chat_auto：自动拼接人名格式
response = model.chat_auto('你好！（招了招手）')
# 自动拼接为：林婉说道："你好！（招了招手）"顾言说道："

# chat：手动格式对话（原样拼接）
response = model.chat('林婉说："你还好吗？"')

# 多角色首字补全：如果模型输出以"顾"开头，自动补全为"顾言"
```

**角色首字补全机制**：

- 设置 `model_name='顾言;林婉'` 时，模型输出的第一个 token 只能采样角色名的首字
- 如果首字匹配（如"顾"），自动强制追加完整名（"言"）
- 遇到换行符或四个空格时停止（不保留），遇到 `"`（右引号）时停止（保留）

***

## 图像特征提取与多模态对话

### 双视觉方案

在1.2.0版本中，我们引入了创新的双视觉方案：

1. **图像压缩转特征(img\_zip)**：将图像转为文本token插入在对话的任何位置
2. **原生视觉编码器**：将最新的一张图片传入原生视觉模型的视觉编码器（标准做法）

这种方案实现了：

- 基于原生视觉编码器对最新单图进行细节分析
- 基于img\_zip技术对上下文中多图的理解能力
- 大幅降低算力资源需求

### 视觉模型使用规范

对于支持视觉的模型，无论是否有图像输入，都应使用以下代码：

```python
from xiaothink.llm.inference.test_formal import QianyanModel

if __name__ == '__main__':
    model = QianyanModel(
        ckpt_dir=r'path/to/your/vision_model',
        MT='t6_standard_vision',  # 注意模型类型为视觉模型
        vocab=r'path/to/your/vocab.txt',
        imgzip_model_path='path/to/img_zip/model.keras'  # 指定img_zip模型路径
    )

    temp = 0.28  # 温度参数
    
    while True:
        inp = input('【问】：')
        if inp == '[CLEAN]':
            print('【清空上下文】\n\n')
            model.clean_his()
            continue
        # 使用chat_vision进行对话
        ret = model.chat_vision(inp, temp=temp, pre_text='', pass_start_char=[])
        print('\n【答】：', ret, '\n')
```

**重要提示**：

- 视觉模型必须使用 `chat_vision` 方法，不能使用 `chat`（仅适用于纯文本模型）
- 必须提前准备好与视觉模型匹配的img\_zip图像压缩编码器模型
- 不匹配的模型会导致模型无法理解编码后的token含义

### 图像处理接口

新增两种图像处理接口：

1. **img2ms**（适用于非原生视觉模型）：
   ```python
   description = model.img2ms('path/to/image.jpg', temp=0.28)
   print(description)
   ```
2. **img2ms\_vision**（适用于原生视觉模型）：
   ```python
   description = model.img2ms_vision('path/to/image.jpg', temp=0.28, max_shape=224)
   print(description)
   ```

### 图像引用语法

在对话中，使用以下语法引用图像：

```python
<img>图像路径或URL</img>请你描述这张图片
```

模型将自动解析图像路径并提取特征，然后根据图像内容进行回答。

**注意事项**：

1. 图像路径需使用绝对路径以确保正确解析
2. 原生视觉模型只支持分析最近的一张图像
3. img\_zip技术支持在上下文中引用多张图像

***

## 图像压缩转特征技术 (img\_zip)

`img_zip` 模块提供了先进的图像和视频压缩/解压功能，基于深度学习的特征提取技术。以下是详细的使用方法：

### 1. 命令行交互模式

```bash
python -m xiaothink.llm.img_zip.img_zip
```

运行后会进入交互式命令行界面：

```
===== img_zip 图像视频压缩工具 =====
请输入.keras模型路径: path/to/your/imgzip_model.keras
模型加载完成!

请选择功能:
1. 压缩图像
2. 解压图像
3. 压缩视频
4. 解压视频
0. 退出

请选择 (0-4): 
```

### 2. Python 代码调用

```python
from xiaothink.llm.img_zip.img_zip import ImgZip

# 初始化实例
img_zip = ImgZip(model_path='path/to/your/imgzip_model.keras')

# 压缩图像
compressed_path = img_zip.compress_image(
    img_path='input.jpg',
    patch=True,  # 是否使用分块处理
    save_path='compressed_img',  # 保存路径前缀
    ability=0.02,# 1.2.5新特性：设置自定义压缩率为0.02（当ability为0时代表不使用自定义压缩率），算法计算并压缩至接近的大小（理论计算与实际存在误差）
)

# 生成两个文件: compressed_img.npy 和 compressed_img.shape

# 解压图像
img_zip.decompress_image(
    compressed_input='compressed_img',  # 压缩文件前缀
    patch=True,  # 是否使用分块处理
    save_path='decompressed.jpg'  # 输出路径
)

# 压缩视频
compressed_paths, metadata_path = img_zip.compress_video(
    video_path='input.mp4',
    output_dir='compressed_video',  # 输出目录
    patch=True  # 是否使用分块处理
)

# 解压视频
img_zip.decompress_video(
    compressed_dir='compressed_video',  # 压缩文件目录
    output_path='decompressed.mp4'  # 输出路径
)

# 图像转数组并保存
img_array = img_zip.image_to_array('input.jpg')
img_zip.save_image_array(img_array, 'image_array.npy')

# 从数组加载图像
loaded_array = img_zip.load_image_array('image_array.npy')
img = img_zip.array_to_image(loaded_array)
img.save('restored.jpg')
```

### 3. 关键功能说明

1. **压缩图像** (`compress_image`)
   - `patch=True`: 将大图切分为80x80块分别处理
   - 输出两个文件: `.npy` (特征向量) 和 `.shape` (原始尺寸信息)
2. **解压图像** (`decompress_image`)
   - 需要`.npy`和`.shape`两个文件
   - 自动恢复原始尺寸
3. **视频处理** (`compress_video`/`decompress_video`)
   - 自动提取视频帧并批量处理
   - 保留原始视频的帧率、分辨率信息
   - 使用临时目录处理中间文件

#### 4. 参数说明

| 参数            | 类型   | 说明                      |
| ------------- | ---- | ----------------------- |
| `model_path`  | str  | img\_zip模型路径 (.keras文件) |
| `patch`       | bool | 是否使用分块处理 (默认为True)      |
| `save_path`   | str  | 输出文件路径前缀                |
| `img_path`    | str  | 输入图像路径                  |
| `video_path`  | str  | 输入视频路径                  |
| `output_dir`  | str  | 输出目录路径                  |
| `output_path` | str  | 输出文件路径                  |

#### 5. 处理流程特点

1. **分块处理**:
   - 大图自动分割为80x80块
   - 每块独立编码为特征向量
   - 保留原始尺寸信息
2. **视频处理**:
   - 自动提取帧并批量处理
   - 保留原始视频参数 (fps, 分辨率)
   - 使用临时目录处理中间文件
3. **进度显示**:
   - 所有操作都带详细进度条
   - 显示当前处理步骤和剩余时间
4. **错误处理**:
   - 完善的异常捕获机制
   - 详细的错误信息提示

#### 6. 使用建议

1. 对于大于80x80的图像，推荐使用分块处理 (`patch=True`)
2. 视频处理需要足够磁盘空间存放临时帧文件
3. 确保输入模型与处理任务匹配
4. 使用绝对路径避免文件定位问题

此模块为Xiaothink视觉模型（尤其是非原生的模型）的核心组件，基于高效的图像特征表示和压缩，可以经过微调让任何纯文本AI模型都拥有基础的视觉能力。

***

## 情感分类工具

情感分类工具基于已加载的对话模型，提供文本情感倾向分析功能，可快速判断输入文本的情感类别（如积极、消极、中性等）。

### 功能说明

- 该工具是基于小思框架（Xiaothink T6系列等）模型的定制化接口
- 基于小思框架语言模型实现情感分类，无需额外加载分类模型
- 支持输入超长文本并返回情感分析结果
- 建议使用单论对话增强模型，例如：Xiaothink-T6-0.15B-ST

### 使用示例

```python
from xiaothink.llm.inference.test_formal import *
from xiaothink.llm.tools.classify import *

if __name__ == '__main__':
    # 初始化基础对话模型
    model = QianyanModel(
        ckpt_dir=r'path/to/your/t6_model',  # 模型权重目录  建议使用_ST版模型
        MT='t6_standard',  # 模型类型（需与权重匹配）
        vocab=r'path/to/your/vocab.txt',  # 词汇表路径
        use_patch=0  # 不使用分块处理（纯文本模型）
    )
    
    # 初始化情感分类模型（依赖基础对话模型）
    cmodel = ClassifyModel(model)
    
    # 循环输入文本进行情感分类
    while True:
        inp = input('输入文本：')
        res = cmodel.emotion(inp)  # 调用情感分类接口
        print(res)  # 输出情感分析结果
```

### 注意事项

1. 情感分类模型依赖已初始化的`QianyanModel`，需确保基础模型加载成功
2. 推荐使用经过指令微调的模型（如`t6_standard`），非微调模型可能影响分类精度
3. 输出结果格式为：{'积极': 0.6667, '消极': 0.1667, '中性': 0.1667}

***

## AI率检测工具

AI率检测工具基于已加载的检测模型，提供文本AI生成概率分析功能，可精准判定文本中各字符的AI生成概率、输出整体AI率均值，并返回精细化的字符级检测详情，实现文本AI生成痕迹的全方位溯源分析。

### 功能说明

- 该工具是基于小思框架（Xiaothink T系列等）模型的定制化接口
- 基于小思框架检测模型实现文本AI率分析，无需额外加载独立检测模型
- 支持超长文本检测、批量文本检测，返回多维度完整检测结果
- 可输出**整体AI率均值、检测结论、概率统计信息、字符级精细化详情** 四层维度结果

### 使用示例

```python
if __name__ == "__main__" and 1:
    # 1. 初始化检测器
    detector = AIDetector(
        ckpt_dir=r'E:\小思框架\论文\ganskchat\ckpt_test_t7',
        model_type='t7',
        print_load_info=True
    )

    # 2. 检测文本
    test_texts = [
        "这是一位活跃在移动互联网上的修车博主在被比亚迪起诉之前，很多期视频开头的一句话，而这位“史上最惨修理工”，终于迎来了被比亚迪起诉的一审判决。",
        "“可不是嘛，”奶奶抬眼望了望桂树，眼神里满是温柔的回忆，“这是你爷爷当年栽的，算下来都快三十年了。那时候他说，栽棵桂树，以后秋天开花，又香又好看，等咱们有了孩子，还能做桂花糕吃。”",
        "这几天心里颇不宁静。今晚在院子里坐着乘凉，忽然想起日日走过的荷塘，在这满月的光里，总该另有一番样子吧。月亮渐渐地升高了，墙外马路上孩子们的欢笑，已经听不见了；妻在屋里拍着闰儿，迷迷糊糊地哼着眠歌。我悄悄地披了大衫，带上门出去。"
    ]

    # 3. 执行检测
    for text in test_texts:
        print(f"\n{'='*60}")
        print(f"检测文本：{text}")
        result = detector.detect_ai_rate(text)
        
        print(f"AI率（概率平均值）：{result['AI率（概率平均值）']}")
        print(f"检测结论：{result['检测结论']}")
        print(f"概率统计：最小={result['概率统计信息']['最小概率']} | 最大={result['概率统计信息']['最大概率']}")
        
        # 可选：打印字符级详情
        print("\n字符级详情：")
        for detail in result['字符级详情']:
            print(f"  位置{detail['字符位置']}：前文「{detail['完整前文']}」→ 字符「{detail['目标字符']}」→ 概率{detail['预测概率']}")

    # 4. 释放资源
    detector.close()
```

### 注意事项

1. AI率检测器初始化时，需确保`ckpt_dir`指向正确的模型权重目录，否则会导致模型加载失败
2. **后端自动选择**：根据 `model_type` 自动选择后端：
   - `t17` 系列模型 → PyTorch 后端
   - `t7.5` / `paddle` 系列模型 → PaddlePaddle 后端
   - 其他模型 → TensorFlow 后端
3. **核心精度说明**：该工具对**小模型生成文本**的AI率检测结果**相对准确**，可满足小模型生成内容的溯源需求；但对**大模型生成文本**的AI率检测效果不佳，检测结果参考价值低，严禁将本工具用于大模型生成内容的AI判定场景
4. 检测完成后必须调用`detector.close()`方法释放显存、硬件句柄等资源，避免长时间运行造成内存泄漏、显存占用过高的问题
5. 字符级详情为可选输出项，针对万字级超长文本，打印该详情会显著增加输出耗时，可根据实际需求选择性打印
6. 批量检测大数量文本时，建议按文本长度分批处理，避免单批次传入过多超长文本导致检测卡顿
7. 模型加载时开启`print_load_info=True`可查看加载进度与硬件适配信息，便于排查模型加载异常问题

### PyTorch 后端示例（T17 模型）

```python
from xiaothink.llm.tools.ai_possibility import AIDetector

if __name__ == "__main__":
    # 初始化检测器（自动选择 PyTorch 后端）
    detector = AIDetector(
        ckpt_dir=r'path/to/your/t17_model',
        model_type='t17_tiny',
        print_load_info=True
    )

    # 检测文本
    test_text = "这是一段待检测的文本内容。"
    result = detector.detect_ai_rate(test_text)
    
    print(f"AI率：{result['AI率（概率平均值）']}")
    print(f"检测结论：{result['检测结论']}")

    # 释放资源
    detector.close()
```

### 阈值校准功能（v1.4.2 新增）

为适应不同场景的检测需求，AI 率检测工具提供了灵活的阈值配置与校准功能。

#### 1. 默认阈值

| 阈值               | 默认值   | 说明                   |
| ---------------- | ----- | -------------------- |
| `threshold_high` | 0.01  | AI率 ≥ 此值判定为"高概率AI生成" |
| `threshold_low`  | 0.005 | AI率 ≥ 此值判定为"疑似AI生成"  |

#### 2. 手动设置阈值

开发者可在初始化时或检测过程中自定义阈值：

```python
# 方式一：初始化时设置
detector = AIDetector(
    ckpt_dir=r'path/to/your/t17_model',
    model_type='t17_tiny',
    threshold_high=0.02,   # 自定义高概率阈值
    threshold_low=0.008    # 自定义疑似AI阈值
)

# 方式二：动态调整
detector.set_thresholds(high=0.015, low=0.006)  # 仅修改高阈值
detector.set_thresholds(low=0.004)               # 仅修改低阈值
```

#### 3. 用户校准功能

通过提供 AI 生成文本和人类文本样本，自动计算最优阈值。每类建议提供 3 条以上文本，文本越长校准越准。

**自动校准**（交互式，适合终端使用）：

```python
detector = AIDetector(
    ckpt_dir=r'path/to/your/t17_model',
    model_type='t17_tiny'
)
# 进入交互式校准：按提示输入 3 段 AI 文本 + 3 段人类文本
calib_result = detector.auto_calibrate()
print(f"校准后高概率阈值: {calib_result['校准后阈值']['高概率阈值']:.6f}")
print(f"校准后疑似AI阈值: {calib_result['校准后阈值']['疑似AI阈值']:.6f}")
```

**编程式校准**（适合代码集成）：

```python
detector = AIDetector(ckpt_dir=r'path/to/your/t17_model', model_type='t17_tiny')

ai_samples = [
    "这是AI生成的第一段测试文本，用于校准检测器的阈值。",
    "这是AI生成的第二段测试文本，内容略有不同。",
    "这是AI生成的第三段测试文本，以便更准确地计算。"
]
human_samples = [
    "这是人类撰写的测试文本，用于区分AI与人类。",
    "这是第二段人类撰写的文本，风格自然流畅。",
    "这是第三段人类样本，用于提高校准的可靠性。"
]

calib_result = detector.calibrate(ai_samples, human_samples)
print(f"校准前阈值: high={calib_result['校准前阈值']['高概率阈值']}, "
      f"low={calib_result['校准前阈值']['疑似AI阈值']}")
print(f"校准后阈值: high={calib_result['校准后阈值']['高概率阈值']}, "
      f"low={calib_result['校准后阈值']['疑似AI阈值']}")
print(f"AI样本平均率: {calib_result['AI率统计']['AI文本平均率']:.6f}")
print(f"人类样本平均率: {calib_result['AI率统计']['人类文本平均率']:.6f}")
```

#### 4. 查看当前阈值配置

```python
info = detector.get_threshold_info()
print(f"高概率阈值: {info['高概率AI阈值']}")
print(f"疑似AI阈值: {info['疑似AI阈值']}")
print(f"已校准: {info['已校准']}")
print(f"校准样本数: {info['校准样本数']}")
```

每次检测结果也会附带当前阈值配置：

```python
result = detector.detect_ai_rate("测试文本")
print(result['阈值配置'])
# 输出: {'高概率阈值': 0.01, '疑似AI阈值': 0.005, '已校准': False}
```

***

## TinySkill 工具箱（v1.4.2 新增）

TinySkill 是 Xiaothink 库提供的一种轻量级技能注册与执行机制。通过注册 prompt 模板和执行类型，用户可以快速让模型完成文本生成或文本分类任务。

每个 TinySkill 可单独设定 **temperature、max\_length、repetition\_penalty** 默认值，运行时可通过 `**kwargs` 覆盖。

> **注意**：截止 Xiaothink-T17 系列发布，所有模型都只支持中文处理，TinySkill 的 prompt 和关键词需使用中文。

### 1. 基础概念

| 概念                    | 说明                             |
| --------------------- | ------------------------------ |
| **TinySkill**         | 一个任务定义，包含 id、名称、prompt 模板、执行类型 |
| **generate 类型**       | 文本生成任务，模型根据 prompt 生成文本        |
| **classify 类型**       | 文本分类任务，基于模型输出中的关键词命中率计算概率      |
| **工具箱 (TinyToolbox)** | 管理 TinySkill 的注册、查询与执行         |

### 2. 快速上手

```python
from xiaothink.llm.inference_torch.torch_formal import TorchModel
from xiaothink.llm.tools.tiny_skill import TinyToolbox, register_default_skills

# 1. 加载模型
model = TorchModel(ckpt_dir="模型权重目录", MT="t17_tiny")
model.set_form("ua_chat")

# 2. 创建工具箱并注册内置技能
toolbox = TinyToolbox(model)
register_default_skills(toolbox)

# 3. 按技能名称执行
result = toolbox.run("题目生成", "春天来了，万物复苏。")
print(result["text"])  # 生成的题目

# 4. 按技能 id 执行
result = toolbox.run("generate_title", "人工智能正在改变世界")
print(result["text"])

# 5. 列出所有内置技能
for sk in toolbox.list_skills():
    print(f"[{sk['id']}] {sk['name']} - {sk['type']} - {sk['description']}")
```

### 3. 注册自定义 TinySkill

#### 3.1 文本生成类 (generate)

生成类技能默认参数：**temperature=0.5, max\_length=64, repetition\_penalty=1.1**

```python
from xiaothink.llm.tools.tiny_skill import TinySkill, TinyToolbox

skill = TinySkill(
    id_="translate_en",
    name="英译中",
    prompt="{input}请将以下内容翻译成英文",
    type_="generate",
    description="将输入文本翻译成英文",
    temperature=0.5,        # skill 级默认温度
    max_length=128,         # skill 级默认生成长度
    repetition_penalty=1.1, # skill 级默认重复惩罚
)
toolbox.register(skill)

result = toolbox.run("translate_en", "今天天气真好")
print(result["text"])
```

#### 3.2 文本分类类 (classify)

分类类技能默认参数：**temperature=0.001, max\_length=128, repetition\_penalty=1.0**

```python
skill = TinySkill(
    id_="spam_detect",
    name="垃圾邮件检测",
    prompt="{input}判断以下内容是否为垃圾邮件，给出分析过程",
    type_="classify",
    keywords=[
        {"name": "垃圾邮件", "id": "0", "key": ["垃圾", "诈骗", "中奖", "点击链接"]},
    ],
    other={"id": "1", "name": "正常邮件"},
    description="判断内容是否为垃圾邮件",
    temperature=0.001,    # 极低温度保证确定性
    repetition_penalty=1.0,
)
toolbox.register(skill)

result = toolbox.run("spam_detect", "恭喜您中奖了！点击领取奖品")
print(f"分类概率: {result['probabilities']}")  # {'0': 0.XX, '1': 0.XX}
print(f"预测: {result['prediction']['name']}")
```

### 4. 分类原理

classify 类型的分类基于 **关键词命中概率**：

1. 用极低温度（0.001）和 repetition\_penalty=1.0 调用模型，得到确定性输出
2. 在模型输出中统计**每个类别关键词**的出现次数（`text.count(keyword)`）
3. 概率 = 该类命中次数 / 总命中次数
4. 若总命中数为 0，归为 `other` 类别（概率 = 1.0）

**示例**：假设分类器定义如下：

- 类别 `"0"`（广告推销）：关键词 `["广告", "营销", "推销"]`
- 类别 `"1"`（生活通知）：other 类别

模型输出为："这条短信涉嫌营销推广，属于广告宣传。"
命中统计：`"广告"×1 + "营销"×1 + "推销"×0 = 2` 次命中
概率：`{"0": 1.0, "1": 0.0}` → 判定为广告推销。

### 5. 内置 TinySkill 列表

| ID                    | 名称   | 类型       | Prompt                              | 默认参数                        | 说明                                                                   |
| --------------------- | ---- | -------- | ----------------------------------- | --------------------------- | -------------------------------------------------------------------- |
| `summarize_word`      | 词语概括 | generate | `{input}请你用一个词语概括内容`                | temp=0.5, maxlen=64, rp=1.1 | 用一个词语概括内容                                                            |
| `summarize_short`     | 短词概括 | generate | `{input}请你用简短的词语概括内容`               | temp=0.5, maxlen=64, rp=1.1 | 用简短词语概括内容                                                            |
| `generate_title`      | 题目生成 | generate | `{input}为这段文本生成题目`                  | temp=0.5, maxlen=64, rp=1.1 | 为文本生成题目                                                              |
| `generate_poem`       | 古诗生成 | generate | `{input}为以上内容生成一段优美古诗`              | temp=0.5, maxlen=64, rp=1.1 | 生成优美古诗                                                               |
| `generate_philosophy` | 哲理文本 | generate | `{input}为以上内容生成一段富有哲理的文本`           | temp=0.5, maxlen=64, rp=1.1 | 生成哲理文本                                                               |
| `generate_jueju`      | 绝句生成 | generate | `关于"{input}"请生成一首绝句`                | temp=0.5, maxlen=64, rp=1.1 | 生成绝句                                                                 |
| `sms_classify`        | 短信分类 | classify | `{input}请你分析这段短信是广告推销还是生活通知？给出推理过程` | temp=0.001, rp=1.0          | 分类广告/生活通知。关键词: 广告、营销、推销、销、宣传；other: 生活通知                             |
| `emotion_analysis`    | 情感分析 | classify | `{input}分析以上文本的情感倾向`                | temp=0.001, rp=1.0          | 分析正面/反面/中性情感。正面关键词: 正、积极、好、愉快、开心、喜欢；反面关键词: 反、消极、坏、差、烂、不、讨厌；other: 中性 |

### 6. 自定义注册示例

```python
# 自定义分类：判断用户反馈类型
feedback_skill = TinySkill(
    id_="feedback_classify",
    name="反馈分类",
    prompt="{input}分析以下用户反馈的类型",
    type_="classify",
    keywords=[
        {"name": "投诉", "id": "0", "key": ["投诉", "不满", "差评", "失望"]},
        {"name": "建议", "id": "1", "key": ["建议", "希望", "改进", "优化"]},
        {"name": "咨询", "id": "2", "key": ["请问", "怎么", "如何", "?"]},
    ],
    other={"id": "-1", "name": "其他"},
    description="分析用户反馈类型（投诉/建议/咨询/其他）",
)
toolbox.register(feedback_skill)
```

### 7. 参数说明与优先级

**参数优先级**：`run(**kwargs)` > `TinySkill 默认值` > `工具箱内部默认值`

**工具箱内部默认值**：

| 类型       | temperature | max\_length | repetition\_penalty |
| -------- | ----------- | ----------- | ------------------- |
| generate | 0.5         | 64          | 1.1                 |
| classify | 0.001       | 128         | 1.0                 |

```python
# 通过 kwargs 覆盖默认参数
result = toolbox.run(
    "古诗生成",
    "秋天景色",
    temperature=0.9,           # 覆盖内置的 0.5
    max_length=256,            # 覆盖内置的 64
    repetition_penalty=1.05,   # 覆盖内置的 1.1
    top_p=0.9,
    stop_conditions=["<", "\n", "。"]  # 自定义停止条件
)
```

***

## ImgTok 视觉支持（v1.4.3 新增）

`xiaothink.llm.xiaothink_img` 模块为视觉语言模型提供图像-文本桥接功能：

```python
from xiaothink.llm.xiaothink_img import ImgProcessor

# 初始化处理器（模型懒加载）
img_proc = ImgProcessor(
    model_path='path/to/phase2_best.pth',  # imgzip 检查点
    device='cuda',
    n_char=512  # 每张图对应的 token 数
)

# 输入侧：将 <imgtoken> 标签替换为 ImgTok token
text_with_images = "<|U|><imgtoken>cat.jpg</imgtoken><|A|>一只猫坐着<|E|>"
processed = img_proc.preprocess_input(text_with_images)
# → "<|U|>ImgTok_107ImgTok_373ImgTok_630...<|A|>一只猫坐着<|E|>"

# 输出侧：从 ImgTok token 重建图像
model_output = "ImgTok_107ImgTok_373...一只猫坐着"
processed = img_proc.postprocess_output(model_output)
# → "<imgtoken>/tmp/xiaothink_img/img_xxx.png</imgtoken>一只猫坐着"

# 清理
img_proc.unload()
```

**工作原理：**

- **编码**：图像 (80×80) → imgzip 压缩器 → 512 个 int8 值 → `ImgTok_{id}` token
- **解码**：`ImgTok_{id}` token → 512 个 int8 值 → imgzip 解压器 → 80×80 RGB 图像
- **Token 映射**：`Token ID = 位置 × 255 + (值 + 127) + 1`
  - 位置 0-511，值 -127\~127 → 每个位置 255 个可能值
  - 总计：512 × 255 = 130,560 个唯一图像 token

**支持的视觉模型：**

| 模型              | MT 参数             | 架构          | 词表大小                                 |
| --------------- | ----------------- | ----------- | ------------------------------------ |
| T17-Tiny-Vision | `t17_tiny_vision` | GRU3 + 历史检索 | 192,894 (52,894 文本 + 140,000 ImgTok) |

**自动集成**：使用 `TorchModel` + `t17_tiny_vision` 时，输入中的 `<imgtoken>` 标签会自动处理，输出中的连续 ImgTok token 会自动重建为图像。

***

## 图像压缩第二代（img\_zip2，v1.4.5 新增）

`xiaothink.llm.img_zip2` 是第二代基于 PyTorch 的图像压缩模块（第一代 `img_zip` 基于 TensorFlow 的后继版本）。将 80×80 图像压缩为 512 个 int8 整数。

```python
from xiaothink.llm.img_zip2 import (
    ImageCompressor, load_checkpoint, MODEL_REGISTRY
)

# 加载模型（需指定 mt 和 checkpoint 路径）
model, ckpt = load_checkpoint(
    'path/to/phase2_best.pth',
    device='cuda',
    mt='test_vmof_2'  # 模型类型
)
model.eval()

# 压缩：(1,3,80,80) tensor → 512 个 int8 值
ints = model.compress(image_tensor)

# 解压：512 个 int8 值 → (1,3,80,80) tensor
recon = model.decompress(ints, device='cuda')
```

**命令行接口：**

```bash
# 完整流程：图像 → .jx → 重建图像
python -m xiaothink.llm.img_zip2.infer input.jpg --ckpt model.pth

# 仅压缩：图像 → .jx 文件（不重建）
python -m xiaothink.llm.img_zip2.infer input.jpg --ckpt model.pth --no_recon

# 仅解压：.jx 文件 → 重建图像
python -m xiaothink.llm.img_zip2.infer input.jx --ckpt model.pth
```

参数说明：

- `input`：输入图像路径（`.jpg`/`.png` 等）或 `.jx` 文件路径
- `--ckpt`：模型 checkpoint 路径（`.pth`，必需）
- `--mt`：模型类型（不指定则从 checkpoint 自动读取）
- `--save_dir`：输出目录
- `--device`：设备（`cuda`/`cpu`，默认 `cuda`）
- `--no_recon`：仅压缩，跳过重建

**交互式 TUI：**

```bash
python -m xiaothink.llm.img_zip2.tui
```

启动交互式菜单，提供以下功能：

1. 压缩图像 → .jx 文件
2. 解压 .jx → 重建图像
3. 完整流程（压缩 + 重建 + PSNR）
4. 图像 → ImgTok token 序列
5. ImgTok token → 重建图像
6. 查看模型信息
7. 退出

**可调 bpp 压缩（v1.4.6 新增）：**

芥象2 通过缩放输入图像来控制 bpp，无需修改模型：

```bash
# 指定缩放因子（scale 越大 bpp 越高，质量越好）
python -m xiaothink.llm.img_zip2.infer input.jpg --ckpt model.pth --scale 0.5

# TUI 中选项 1「压缩图像」提供交互式档位选择
python -m xiaothink.llm.img_zip2.tui
```

```python
from xiaothink.llm.img_zip2 import SCALES, calc_bpp, infer_one

# 7 档缩放: [0.25, 0.35, 0.5, 0.7, 1.0, 1.4, 2.0]
for scale in SCALES:
    jx_path, recon = infer_one('photo.jpg', 'model.pth', scale=scale)

# bpp = jx字节数 × 8 / 原图像素数
bpp = calc_bpp(os.path.getsize('photo.jx'), W_orig, H_orig)
```

bpp 调控原理：输入图缩放 → 块数变化 → 总字节变化 → bpp 变化（每个 80×80 块的内部压缩固定为 512 ints → LZMA）

| scale | 输入尺寸 (以2048×1365为例) | 块数     | 预估 bpp |
| ----- | ------------------- | ------ | ------ |
| 0.25x | 512×341             | \~35   | \~0.08 |
| 0.50x | 1024×682            | \~117  | \~0.15 |
| 1.00x | 2048×1365           | \~442  | \~0.27 |
| 2.00x | 4096×2730           | \~1820 | \~0.55 |

**与第一代的关键区别：**

| 特性     | img\_zip（第一代）        | img\_zip2（第二代）                      |
| ------ | -------------------- | ----------------------------------- |
| 框架     | TensorFlow/Keras     | PyTorch                             |
| 模型格式   | `.keras`             | `.pth`                              |
| 架构     | 单一自编码器               | 三专家 + 后处理层（>100M 参数）                |
| MT 注册表 | 无                    | `MODEL_REGISTRY` 动态路由               |
| 加载方式   | `ImgZip(model_path)` | `load_checkpoint(path, device, mt)` |

**用于 LLM 集成**：使用带 `mt` 参数的 `ImgProcessor`：

```python
from xiaothink.llm.xiaothink_img import ImgProcessor

img_proc = ImgProcessor(
    model_path='path/to/phase2_best.pth',
    device='cuda',
    mt='test_vmof_2'  # 显式指定模型类型
)
```

***

## OpenAI 兼容服务器与网页聊天（v1.4.7 新增）

`xiaothink.llm.inference_torch.openai_server` 模块提供了 OpenAI 格式兼容的 API 服务器，支持流式与非流式聊天补全。

### 启动服务器

```python
from xiaothink.llm.inference_torch.torch_formal import TorchModel
from xiaothink.llm.inference_torch.openai_server import OpenAIServer

# 加载模型
model = TorchModel(ckpt_dir='path/to/model', MT='t17_tiny')

# 启动服务器（不带网页界面）
server = OpenAIServer(model, host='127.0.0.1', port=8000)
server.run()
```

### 启用网页聊天界面

```python
# 添加 use_gui=True 启动内置聊天页面
server = OpenAIServer(model, host='127.0.0.1', port=8000, use_gui=True)
server.run()
# 访问 http://127.0.0.1:8000/ 即可使用
```

网页界面支持：调参（temperature/top\_p/max\_tokens/repetition\_penalty）、对话/续写模式切换、清空历史。

### 使用 API 密钥鉴权

```python
server = OpenAIServer(model, host='0.0.0.0', port=8000, api_key='sk-your-key')
server.run()
```

### 通过 OpenAI 客户端调用

```python
from openai import OpenAI

client = OpenAI(
    base_url='http://127.0.0.1:8000/v1',
    api_key='sk-your-key'  # 如未设置 api_key 可填任意值
)

# 流式聊天
stream = client.chat.completions.create(
    model='xiaothink',
    messages=[{'role': 'user', 'content': '你好'}],
    temperature=0.85,
    top_p=0.9,
    max_tokens=512,
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content or '', end='')

# 非流式聊天
response = client.chat.completions.create(
    model='xiaothink',
    messages=[{'role': 'user', 'content': '你好'}],
    stream=False
)
print(response.choices[0].message.content)
```

***

小思框架系列模型名称、其对应MT（模型架构版本）以及form（模型prompt传入格式）一览：

| 模型名称（按发布时间）                | mt 参数                              | form 参数         |
| -------------------------- | ---------------------------------- | --------------- |
| Xiaothink-T17-Tiny         | mt='t17\_tiny'                     | 无需 form 参数      |
| Xiaothink-T17-Tiny-Vision  | mt='t17\_tiny\_vision'             | 无需 form 参数      |
| Xiaothink-T17-MoE-2B       | mt='t17\_moe\_2b\_a0.15b'          | 无需 form 参数      |
| Xiaothink-T7.5-0.1B        | mt='t7.5\_paddle\_small\_instruct' | form=2          |
| Xiaothink-T7-ART(0.07B)    | mt='t7\_cpu\_standard'             | form=1          |
| Xiaothink-T6-0.08B         | mt='t6\_beta\_dense'               | form=1          |
| Xiaothink-T6-0.15B         | mt='t6\_standard'                  | form=1          |
| Xiaothink-T6-0.02B         | mt='t6\_fast'                      | form=1          |
| Xiaothink-T6-0.5B          | mt='t6\_large'                     | form=1          |
| Xiaothink-T6-0.5B-pretrain | mt='t6\_large'                     | form='pretrain' |

***

## 更新日志

### 版本 1.4.9 (2026-08-09)

- **新增功能 - checkpoint 自动检索（PyTorch 推理）**：
  - `TextGenerator.load_model` 在 `final_model.pt` 和 `checkpoints/` 子目录都不存在时，自动检索模型目录中的所有 `.pt` 文件
  - 加载优先级：`final_model.pt`（根目录）→ `checkpoints/checkpoint_N.pt`（子目录）→ 根目录下任意 `.pt` 文件
  - 根目录 `.pt` 检索优先选择 `checkpoint_N.pt` 命名（按 batch 号排序），否则取修改时间最新的文件
  - 支持权重与 tokenizer 文件全部放在同一目录、没有 `checkpoints/` 子目录的模型加载

### 版本 1.4.8 (2026-07-20)

- **新增模型 - t17\_rwkv5\_mla（RWKV-v5 + MLA 纯历史检索）**：
  - 添加 `t17_rwkv5_mla` 和 `t17_rwkv5_mla_instruct` 模型架构
  - 核心架构：RWKV-v5 并行时间混合 + DeepSeek V3 MLA（Multi-head Latent Attention）纯历史检索门控
  - 职责分离：RWKV 负责当前信息建模（指数衰减局部注意力），MLA 负责长程历史检索（稀疏快照 + 标准 softmax 全注意力）
  - NoPE 位置编码：Q/K 纯 content-only，无 RoPE，QK-Norm 稳定点积尺度
  - 低秩压缩存储：KV latent 维度 = d\_model // 2，解压后独立 K/V 投影（K ≠ V）
  - Gate 融合：combined\_out = time\_out + gate \* h\_ctx，支持 freeze\_gate 冻结门控
  - 训练显存友好：K/V 保持 \[B, H, ...] 形状不展开 T 维，einsum 广播计算
  - 冷启动安全：score 层面拼接当前步自身，H=0 时 softmax 仍有归一化目标
  - KV Cache 推理加速：解压后的 K/V 缓存避免每步重复 decompress
  - 模型配置：d\_model=1400, num\_heads=4, num\_layers=16, save\_every=32
  - 添加独立模型文件 `t17_rwkv5mla_model.py`，包含完整架构文档和伪代码
  - 训练代码中的 `MT_NAME='t17_rwkv5_mla'` 配置及 `freeze_gate`/`use_kv_cache` 开关

### 版本 1.4.7 (2026-07-16)

- **新增功能 - OpenAI 兼容服务器与网页聊天**：
  - 添加 `xiaothink.llm.inference_torch.openai_server` 模块
  - `OpenAIServer(model, host, port)` — 启动 OpenAI 兼容 API 服务器
  - `POST /v1/chat/completions` — 支持 `temperature`、`top_p`、`max_tokens`、`stream` 参数
  - `GET /v1/models` — 列出可用模型
  - `use_gui=True` 时启用网页聊天界面，支持调参、对话/续写模式切换、清空历史
  - 流式 SSE 输出，5-token 缓冲机制防止 stop marker 泄漏
  - 基于 Xiaothink 历史格式（`<|U|>`/`<|A|>`）实现 messages → prompt 转换
  - 支持 Bearer Token API 密钥鉴权（`api_key` 参数）

### 版本 1.4.6 (2026-06-29)

- **新增功能 - 可调 bpp 压缩**：
  - 芥象2 通过缩放输入图像控制 bpp：`infer_one` / CLI 新增 `--scale` 参数
  - 7 档预设缩放 `SCALES = [0.25, 0.35, 0.5, 0.7, 1.0, 1.4, 2.0]`
  - 新增 `calc_bpp(jx_bytes, w, h)` 计算 bits per pixel
  - bpp = jx字节数 × 8 / 原图像素数，scale 越小 bpp 越低
  - TUI 压缩选项提供交互式档位选择和自定义缩放因子
  - 导出 `SCALES`、`calc_bpp` 到 `xiaothink.llm.img_zip2`
  - 注意：图像→token 功能（img2llm）不受 bpp 影响，固定 80×80→512 ints

### 版本 1.4.5 (2026-06-29)

- **新增模块 - img\_zip2（图像压缩第二代）**：
  - 添加 `xiaothink.llm.img_zip2` 模块：基于 PyTorch 的极端图像压缩（80×80 ↔ 512 个 int8）
  - 三专家空间自编码器：深层窄专家(DN) + 浅层宽专家(SW) + ViT 专家，软路由门控融合
  - 迭代后处理层(PostProcessor)：扩散模型风格步数嵌入，逐步优化图像质量（总参数量 > 100M）
  - `MODEL_REGISTRY` MT 机制：根据模型类型动态路由到对应的编码器/解码器架构
  - 子模块：`img_compressor`（核心模型 + 训练）、`img2llm`（图像 ↔ LLM token 桥接）、`infer`（任意尺寸切块 + .jx 格式）
  - `load_checkpoint(path, device, mt)`：自动从 checkpoint 检测 MT，支持显式 `mt` 覆盖
- **重构** **`xiaothink_img.py`**：
  - 现在从 `xiaothink.llm.img_zip2` 导入，不再依赖外部 `v16/imgzip2`
  - `ImgProcessor` 和 `get_img_model()` 新增 `mt` 参数，支持显式指定模型类型
  - `LATENT_DIM`/`INT_SCALE`/`NUM_VALUES` 从加载的模型动态读取，不再硬编码
  - `model_path` 现在为必需参数（不再回退到 `CONFIG['pretrained']`）
- **兼容性**：现有 `TorchModel`/`TorchNovelModel` API 不变 — 接受 `imgzip_checkpoint` 并在内部创建 `ImgProcessor`

### 版本 1.4.4 (2026-06-28)

- **新增类 - TorchNovelModel**：
  - 添加 `xiaothink.llm.inference_torch.torch_novel.TorchNovelModel` 小说角色扮演模型
  - 继承 `TorchModel`，新增小说对话专用接口
  - `set_model_name()`：设置模型扮演角色名，支持多角色用 `;` 分隔（如 `'顾言;林婉'`）
  - `set_user_name()`：设置用户扮演角色名
  - `set_setting()`：设置故事背景
  - `chat_auto()`：自动格式对话——自动拼接 `{user_name}："{text}"\n` 传入模型
  - `chat()`：手动格式对话——原样拼接用户输入
  - 多角色自动补全：如果模型输出首字匹配角色名（如'顾'），自动补全完整名（'言'）
  - 遇到换行符或四个空格停止（不保留），遇到 `"` 停止（保留）
  - 完整 ImgTok 视觉支持，支持显式传入 `imgzip_checkpoint` 参数
- **API 增强 - TorchModel**：
  - `TorchModel.__init__()` 新增 `imgzip_checkpoint` 参数，支持显式指定 imgzip 模型路径
  - 图像 token 处理在 `TorchModel`/`TorchNovelModel` 层完成，底层 `torch_test.py` 不负责
- **Bug 修复**：
  - 修复 `t17_tiny_vision` 推理时 tensor size mismatch 错误：`t17_tiny_vision` 未在 `RNN_FAMILY_NAMES` 中，导致使用完整序列模式时 `history_tensor` 溢出
  - 修复推理时 `max_history_len` 过小（原 `512 // save_every = 2`，现最小 64 并支持动态扩展）

### 版本 1.4.3 (2026-06-19)

- **新增模块 - ImgTok 视觉支持**：
  - 添加 `xiaothink.llm.xiaothink_img` 模块，实现图像-文本桥接
  - `ImgProcessor` 类：统一的图像 ↔ ImgTok token 转换
  - 输入预处理：`<imgtoken>图片路径</imgtoken>` 标签自动通过 imgzip 压缩器转为 `ImgTok_{id}` 序列（80×80 → 512个 int8 → ImgTok tokens）
  - 输出后处理：连续 `ImgTok_{id}` 序列（≥512个）自动通过 imgzip 解码器重建图像，替换为 `<imgtoken>临时文件路径</imgtoken>` 标签
  - 懒加载单例模型，高效复用
  - 文本处理函数：`replace_imgtoken_tags()`、`replace_imgtok_with_tags()`、`extract_imgtok_groups()`
- **新增模型**：
  - 添加 `t17_tiny_vision` 模型：GRU3 + 历史检索架构的图文混合模型。配置：d\_model=768, num\_heads=8, num\_layers=12, history\_top\_k=8。检查点目录：`ckpt_test_t17_tiny_vision`
- **新词汇表**：
  - 添加 `vocab_img.json`：原 52,894 个 token + 140,000 个 ImgTok (ImgTok\_1 \~ ImgTok\_140000)，共 192,894 个 token
  - Token 映射：`Token ID = 位置 × 255 + (值 + 127) + 1`，覆盖 512 个位置 × 255 个值 = 130,560 个唯一图像 token
  - `WordTokenizer.tokenize()` 现已支持 `ImgTok_` 前缀的专用快速匹配路径
- **训练改进**：
  - 添加 `CPU Offload` 机制（`USE_CPU_OFFLOAD`），优化器状态常驻 CPU 以降低 GPU 显存
  - 添加 `Inexact Autoregression` 训练模式（`USE_INEXACT_AR`, `INEXACT_AR_CUT_EVERY`）：每 N 个位置才预测一次，减少 llm\_head 计算量和 logits 显存
  - 优化器状态卸载：在 optimizer step 之间将 Adam 的 exp\_avg/exp\_avg\_sq 移至 CPU
- **模型加载**：
  - Embedding 层扩展：加载较小词汇表的检查点时，保留预训练权重，随机初始化新 token
  - 支持 `STRICT_LOAD=False` 模式的智能词汇表扩展
- **更新文件**：
  - `torch_test.py`：集成 ImgTok 输入预处理和输出后处理
  - `torch_train.py`：在 `_create_encoded_cache()` 中添加 `<imgtoken>` 标签处理
  - `torch_models.py`：添加 `t17_tiny_vision` 配置和模型创建分支
  - 所有训练文件默认使用 `vocab_img.json`
  - `setup.py` 依赖添加 `Pillow>=9.0.0` 用于图像处理

### 版本 1.4.2 (2026-06-10)

- **新增模块**：
  - 添加 `xiaothink.llm.inference_torch` 模块，支持基于 PyTorch 的推理
  - 支持 Xiaothink-T17 系列模型（GRU/LSTM 架构 + 历史检索机制）
  - 提供 `TorchModel` 类用于 PyTorch 推理
  - 新增 `TinySkill` 工具箱（`xiaothink.llm.tools.tiny_skill`），支持轻量级技能注册与执行（generate / classify 两种类型），内置 8 个默认技能（词语概括、短词概括、题目生成、古诗生成、哲理文本、绝句生成、短信分类、情感分析）
- **模型特性**：
  - 创新的历史检索机制：生成时检索相关历史上下文
  - 门控融合：可学习的门控机制融合 RNN 输出与检索历史
  - 因果掩码：确保训练和推理时无未来信息泄露
  - 高效推理：针对端侧部署优化，内存占用低
- **支持的 MT 架构**：
  - 't17\_tiny': 基于 GRU 的历史检索模型
- **AI 率检测增强**：
  - 新增阈值校准功能：`calibrate()` 和 `auto_calibrate()` 方法，通过 AI/人类文本样本自动计算最优阈值
  - 新增手动阈值调整：`set_thresholds(high, low)` 方法，开发者可自定义阈值
  - `__init__` 新增 `threshold_high` 和 `threshold_low` 参数，初始化即可设置
  - 检测结果新增 `阈值配置` 字段，包含当前阈值和校准状态
  - 重构后端导入顺序（PyTorch > PaddlePaddle > TensorFlow），修复 numpy 2.0 导致 TensorFlow 崩溃并污染其他后端的问题
  - 新增 `XIAOTHINK_BACKEND` 环境变量支持，可指定只导入某个后端（`torch`/`paddle`/`tensorflow`/`auto`），完全跳过其他后端的导入，避免兼容性问题

### 版本 1.4.1 (2026-02-16)

- **新增模块**：
  - 添加 `xiaothink.llm.inference_paddle` 模块，支持基于 PaddlePaddle 的推理
  - 支持 Xiaothink-T7.5 系列模型（RWKV 架构）
  - 提供 `TextGenerator` 和 `QianyanModel` 类用于 PaddlePaddle
- **更新依赖**：
  - 移除 TensorFlow 作为必需依赖（现为可选）
  - 添加 PaddlePaddle 作为主要深度学习框架
  - 添加 jieba 用于中文分词
- **模型支持**：
  - 添加 MT 架构支持：'t7.5\_paddle\_small\_instruct', 't7.5\_paddle\_small\_instruct\_pro' 等
  - 支持基于 GPU 内存使用率的自动设备选择（CPU/GPU）

### 版本 1.4.0 (2026-02-16)\[Yanked]

- **Note**：由于README.md文件内容有误，该版本已被标记为不推荐使用，请使用更新的版本。

### 版本 1.3.2 (2025-12-27)

- **更新接口**：
  - 添加了基于xiaothink-T系列模型的“AI率检测”接口。
- **新增模型**：
  - 添加了Xiaothink-T7系列模型中MT为"t7"与"t7\_cpu\_standard"的架构的支持。

### 版本 1.3.1 (2025-10-31)

- **更新接口**：
  - 为视觉相关接口添加了自定义输入shape（须对应模型支持）而非以前版本的固定80*80*3
  - ImgZIP命令行版接口也同步添加了自定义输入shape（须对应模型支持）而非以前版本的固定80*80*3，并加入了基于SNR、PSNR、SSIM的综合质量得分。

### 版本 1.3.0 (2025-10-17)\[已Yank]

- **新增模型**：
  - 添加了Xiaothink-T7系列模型架构的支持。

### 版本 1.2.5 (2025-09-02)

- **更新接口**：
  - ImgZIP命令行版接口添加“自定义压缩率”功能，支持自定义模型原生压缩率之外的其他压缩率（基于计算并缩放原图实现）。

### 版本 1.2.4 (2025-08-30)

- **更新接口**：
  - 更新文档中ImgZIP相关接口的导入方法为：from xiaothink.llm.img\_zip.img\_zip import ImgZip

### 版本 1.2.3 (2025-08-30)

- **新增功能**：
  - 添加了Xiaothink-T6-0.02B系列模型（MT='t6\_fast'）
  - 添加了Xiaothink-T6-0.5B系列模型（MT='t6\_large'）
  - 在model.chat方法中添加了form='pretrain'的支持，t6系列指令微调的模型应使用form=1，预训练模型应使用form='pretrain'

### 版本 1.2.2 (2025-08-18)

- **新增功能**：
  - 新增情感分类工具，通过`ClassifyModel`实现文本情感倾向分析
  - 新增`xiaothink.llm.tools.classify`模块，支持基于基础对话模型的情感分类
  - 提供`cmodel.emotion(inp)`接口，实时返回文本情感结果

### 版本 1.2.1 (2025-08-16)

- **新增模型**：
  - 添加了Xiaothink-T6-0.15B系列模型（MT='t6\_standard'）

### 版本 1.2.0 (2025-08-08)

- **突破性创新**：
  - 添加对原生视觉模型的支持，采用创新的双视觉方案
  - 图像压缩转特征token(img\_zip) + 原生视觉编码器双路处理
  - 既保留多图上下文理解能力，又实现单图细节分析
- **新增接口**：
  - `model.chat_vision`：视觉模型专用对话接口
  - `model.img2ms`：非原生视觉模型图像描述接口
  - `model.img2ms_vision`：原生视觉模型图像描述接口（支持max\_shape参数）
- **模块扩展**：
  - 新增 `xiaothink.llm.img_zip.img_zip` 命令行工具
  - 支持图像和视频的压缩与解压
  - 提供丰富的参数调节压缩质量
- **使用规范**：
  - 视觉模型必须使用 `chat_vision` 方法
  - 必须使用匹配的img\_zip编码器模型
  - 图像路径需使用绝对路径

### 版本 1.1.0 (2025-08-02)

- **新增功能**：
  - 添加`img2ms`和`ms2img`接口，实现图像的高压缩率有损压缩
  - 支持将图像转换为AI可读的特征tokens
  - 扩展对话模型支持多模态输入（图像+文本）
  - test\_formal中，默认支持将多模态AI生成的特征tokens转为图像并保存至系统临时文件夹。
- **技术升级**：
  - 基于小思框架自研的img\_zip技术
  - 支持80x80x3图像块的智能压缩
  - 当输出为96个特征值时，结合.7z算法可实现10%超高压缩率
- **使用方式**：
  - 在对话中使用`<img>{image_path}</img>`标签插入图像
  - 初始化模型时需指定img\_zip模型路径
  - 支持多模态对话（图像描述、图像问答等场景）

***

以上就是 Xiaothink Python 模块的主要功能及使用方法。

如有任何疑问或建议，请随时联系我们：<xiaothink@foxmail.com>。
