Xiaothink Python 模块使用文档

Xiaothink 是一个以自然语言处理（NLP）为核心的AI研究组织，致力于在少数据、低算力下训练出先进的端侧模型。Xiaothink Python 模块是我们提供的核心工具包，涵盖了文本问答、图文问答、图像压缩、情感分类等多种功能。以下是详细的使用指南和代码示例。

安装
License
本地纯文本对话模型
基于 PaddlePaddle 的模型（v1.4.0 新增）
基于 PyTorch 的模型（T17，v1.4.2 新增）
- 翻译功能
- 小说角色扮演（v1.4.4 新增）
图像特征提取与多模态对话
图像压缩转特征技术 (img_zip)
情感分类工具
AI率检测工具
TinySkill 工具箱（v1.4.2 新增）
ImgTok 视觉支持（v1.4.3 新增）
图像压缩第二代（img_zip2，v1.4.5 新增）
OpenAI 兼容服务器与网页聊天（v1.4.7 新增）
小思框架系列模型名称
更新日志

安装

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

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）：

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

示例（Linux/Mac）：

# 只使用 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 file for details.

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

本地纯文本对话模型

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

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

适用于单轮对话场景。

示例代码

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')

多轮对话

适用于多轮对话场景。

示例代码

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 方法可以手动添加历史对话记录，适用于预设对话上下文的场景。

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 参数

文本续写

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

示例代码

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 架构模型。这些模型提供高效的推理能力，适合资源受限的环境。

安装

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

多轮对话（PaddlePaddle）

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）

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 内存使用率自动选择最优设备：

# 自动设备选择（默认）
# 如果 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 工作原理：

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

核心特性：

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

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 时指定自己的训练数据路径：

# 默认行为（使用内置路径）
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 会在以下位置查找训练数据：

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

内存优化：

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

支持的文件格式

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

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

支持的数据结构

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

1. 对话格式（Conversations Format）

{
  "conversations": [
    {"content": "User question"},
    {"content": "Assistant answer"}
  ]
}

2. 指令-输出格式（Instruction-Output Format）

{
  "instruction": "Instruction content",
  "output": "Output content"
}

内存优化：

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

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

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

安装

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

多轮对话（PyTorch）

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）

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() 方法，支持英译中、中译英模式：

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，专为小说角色扮演场景设计，支持多角色自动接话和故事背景设置。

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版本中，我们引入了创新的双视觉方案：

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

这种方案实现了：

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

视觉模型使用规范

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

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含义

图像处理接口

新增两种图像处理接口：

img2ms（适用于非原生视觉模型）：

description = model.img2ms('path/to/image.jpg', temp=0.28)
print(description)

img2ms_vision（适用于原生视觉模型）：

description = model.img2ms_vision('path/to/image.jpg', temp=0.28, max_shape=224)
print(description)

图像引用语法

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

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

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

注意事项：

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

图像压缩转特征技术 (img_zip)

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

1. 命令行交互模式

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 代码调用

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. 关键功能说明

压缩图像 (compress_image)
- patch=True: 将大图切分为80x80块分别处理
- 输出两个文件: .npy (特征向量) 和 .shape (原始尺寸信息)
解压图像 (decompress_image)
- 需要.npy和.shape两个文件
- 自动恢复原始尺寸
视频处理 (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. 处理流程特点

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

6. 使用建议

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

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

情感分类工具

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

功能说明

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

使用示例

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)  # 输出情感分析结果

注意事项

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

AI率检测工具

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

功能说明

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

使用示例

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()

注意事项

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

PyTorch 后端示例（T17 模型）

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. 手动设置阈值

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

# 方式一：初始化时设置
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 条以上文本，文本越长校准越准。

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

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}")

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

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. 查看当前阈值配置

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

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

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. 快速上手

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

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

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 类型的分类基于 关键词命中概率：

用极低温度（0.001）和 repetition_penalty=1.0 调用模型，得到确定性输出
在模型输出中统计每个类别关键词的出现次数（text.count(keyword)）
概率 = 该类命中次数 / 总命中次数
若总命中数为 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. 自定义注册示例

# 自定义分类：判断用户反馈类型
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

# 通过 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 模块为视觉语言模型提供图像-文本桥接功能：

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 整数。

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')

命令行接口：

# 完整流程：图像 → .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：

python -m xiaothink.llm.img_zip2.tui

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

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

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

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

# 指定缩放因子（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

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：

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 服务器，支持流式与非流式聊天补全。

启动服务器

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()

启用网页聊天界面

# 添加 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 密钥鉴权

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

通过 OpenAI 客户端调用

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（须对应模型支持）而非以前版本的固定80803
- ImgZIP命令行版接口也同步添加了自定义输入shape（须对应模型支持）而非以前版本的固定80803，并加入了基于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。

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xiaothink-1.4.9.tar.gz (369.6 kB view details)

Uploaded Aug 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

xiaothink-1.4.9-py3-none-any.whl (346.2 kB view details)

Uploaded Aug 9, 2026 Python 3

File details

Details for the file xiaothink-1.4.9.tar.gz.

File metadata

Download URL: xiaothink-1.4.9.tar.gz
Upload date: Aug 9, 2026
Size: 369.6 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.9.0

File hashes

Hashes for xiaothink-1.4.9.tar.gz
Algorithm	Hash digest
SHA256	`3d7e279cfbff2123c96ba538e4196ad8f8378fb50f3db399f732820928d92554`
MD5	`2369f6d2193edaba107ad55a34ad6389`
BLAKE2b-256	`ac81065e50f3060e620f7351fba6eb0365336be9854899005e6d01ef81e39ae6`

See more details on using hashes here.

File details

Details for the file xiaothink-1.4.9-py3-none-any.whl.

File metadata

Download URL: xiaothink-1.4.9-py3-none-any.whl
Upload date: Aug 9, 2026
Size: 346.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.9.0

File hashes

Hashes for xiaothink-1.4.9-py3-none-any.whl
Algorithm	Hash digest
SHA256	`6a492a5e04af2d331cacd527a0d0cd39533a669210d5ee62d8e7e38b11ee3429`
MD5	`ccda0fe237e3a39a9e9cb06011304bd3`
BLAKE2b-256	`b2d1b6f66e8076e159bb0a05bf8fcf6add64b40a1cf71f82b2ef9b5bb3639882`

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.4.9

Aug 9, 2026

1.4.8

Aug 7, 2026

1.4.7

Jul 16, 2026

1.4.5

Jun 29, 2026

1.4.2

Jun 13, 2026

1.4.1

Feb 16, 2026

1.4.0

Feb 16, 2026

1.3.2

Dec 27, 2025

1.3.0 yanked

Oct 17, 2025

Reason this release was yanked:

Parameter-passing related errors occur when calling the vision-related interfaces of xiaothink.llm.inference.test_formal.

1.2.6

Sep 2, 2025

1.2.5.2

Sep 2, 2025

1.2.4

Aug 30, 2025

1.2.3

Aug 30, 2025

1.2.2

Aug 19, 2025

1.2.1

Aug 16, 2025

1.2.0

Aug 9, 2025

1.1.0

Aug 2, 2025

1.0.5

Jul 16, 2025

1.0.4

Mar 15, 2025

1.0.3

Jan 29, 2025

1.0.2

Dec 22, 2024

1.0.1

Dec 15, 2024

1.0.0

Dec 15, 2024

xiaothink 1.4.9

Xiaothink Python 模块使用文档

目录

安装

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

License

本地纯文本对话模型

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

示例代码

多轮对话

示例代码

手动添加历史对话

文本续写

示例代码

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

安装

多轮对话（PaddlePaddle）

文本生成（PaddlePaddle）

支持的模型架构（PaddlePaddle）

自动设备选择

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

支持的文件格式

支持的数据结构

1. 对话格式（Conversations Format）

2. 指令-输出格式（Instruction-Output Format）

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

安装

多轮对话（PyTorch）

文本生成（PyTorch）

支持的模型架构（PyTorch）

核心特性

翻译功能（PyTorch）

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

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

双视觉方案

视觉模型使用规范

图像处理接口

图像引用语法

图像压缩转特征技术 (img_zip)

1. 命令行交互模式

2. Python 代码调用

3. 关键功能说明

4. 参数说明

5. 处理流程特点

6. 使用建议

情感分类工具

功能说明

使用示例

注意事项

AI率检测工具

功能说明

使用示例

注意事项

PyTorch 后端示例（T17 模型）

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

1. 默认阈值

2. 手动设置阈值

3. 用户校准功能

4. 查看当前阈值配置

TinySkill 工具箱（v1.4.2 新增）

1. 基础概念

2. 快速上手

3. 注册自定义 TinySkill

3.1 文本生成类 (generate)

3.2 文本分类类 (classify)

4. 分类原理

5. 内置 TinySkill 列表

6. 自定义注册示例

7. 参数说明与优先级

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

图像压缩第二代（img_zip2，v1.4.5 新增）

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

启动服务器

启用网页聊天界面

使用 API 密钥鉴权

通过 OpenAI 客户端调用

更新日志

版本 1.4.9 (2026-08-09)

版本 1.4.8 (2026-07-20)

版本 1.4.7 (2026-07-16)