Metadata-Version: 2.4
Name: tgai-go
Version: 1.1.0
Summary: TGAI GO —— 纯 Python 的 TGAI 模型推理库（CPU 引擎，零编译安装）
Author: TGAI
License-Expression: MIT
Project-URL: Homepage, https://github.com/JXW666NB/TGAI-GO
Project-URL: Issues, https://github.com/JXW666NB/TGAI-GO/issues
Project-URL: Documentation, https://github.com/JXW666NB/TGAI-GO#readme
Project-URL: Repository, https://github.com/JXW666NB/TGAI-GO
Keywords: tgai,llm,inference,moe,chinese,llama
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Provides-Extra: tokenizer
Requires-Dist: tokenizers>=0.15; extra == "tokenizer"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# TGAI GO

**纯 Python 的 TGAI 模型推理库** —— `pip install` 后即可加载 `.TG` 模型推理，无需编译、无需 CUDA、无需 Vulkan SDK。

```python
import tgai_go

m = tgai_go.load("v27_merged_bf16.TG")
print(m.generate("什么是机器学习？", max_tokens=128))
```

---

## 特性

| 特性 | 说明 |
|---|---|
| **零编译安装** | 原生引擎（C + OpenMP）以预编译库随包分发，`pip install tgai-go` 即可用 |
| **无外部依赖** | 引擎只依赖系统 `kernel32`（静态链接 CRT）；Python 侧只要 `numpy` |
| **CPU 推理** | 纯 CPU，8 线程实测 **12.0 tok/s**（28 层 MoE，5.6 GB BF16 权重） |
| **多轮对话** | 内置 KV cache 复用，跨轮只算新增 token |
| **配置随模型走** | `.TG` 可内嵌对话模板（九标记 / ChatML / 纯文本），库自动读取 |
| **流式输出** | `for chunk in m.stream(...)` 逐段拿文本 |
| **CPU 友好** | 不需要独显；核显机器、笔记本、服务器都能跑 |

---

## 安装

```bash
pip install tgai-go
```

> 平台：Windows x64 已实测；Linux/macOS 需自行编译原生库（见文末）。

---

> 📖 **第一次使用？看 [使用手册.md](使用手册.md)** —— 3 步跑通，含必踩的坑。

## 快速开始

### 单轮生成

```python
import tgai_go

m = tgai_go.load("v27.TG")

print(m.generate("什么是人工智能？"))
print(m.generate("写一句关于春天的话。", max_tokens=64, stop=["。"]))
```

### 多轮对话（自动带历史）

```python
with tgai_go.load("v27.TG") as m:
    s = m.session(system="你是 TGAI，一个中文助手")
    print(s.chat("我叫小明，今年8岁。"))
    print(s.chat("我叫什么名字？"))     # → "你叫小明，今年8岁。"
    print(s.chat("我几岁了？"))         # → "8岁"
```

### 流式输出

```python
with tgai_go.load("v27.TG") as m:
    for chunk in m.stream("讲个短故事", max_tokens=200):
        print(chunk, end="", flush=True)
```

### 性能调节

```python
m = tgai_go.load("v27.TG", threads=8, preload=True)
print(m.threads)          # 8

# 实测（Ryzen 7 7730U, 8C/16T, V2.7 28层 MoE）：
#   4 线程  → 约 11 tok/s   ← 默认值，已饱和
#   8 线程  → 约 11 tok/s   （无增益）
#  16 线程  → 约 10 tok/s   （超线程反而略慢）
#  说明：瓶颈是内存带宽，不是算力 —— 每 token 要把 1.7 GB 权重过一遍
#        （V2.7 BF16）。想更快只能降精度，加线程没用。
```

---

## API

### `tgai_go.load(path, *, dll=None, extend_ctx=0, threads=None, preload=False)`

| 参数 | 说明 |
|---|---|
| `path` | `.TG` 模型路径 |
| `dll` | 指定引擎库（默认用包内 `_native/`） |
| `extend_ctx` | 扩展上下文（NTK-by-parts / YaRN），0 = 用模型自带 `max_seq` |
| `threads` | CPU 线程数；`None` = 引擎默认，`0` = 全部逻辑核 |
| `preload` | `True` = 预解码全部权重（首次推理不卡顿，但占更多内存） |

返回 `Model` 对象，支持 `with` 语句自动释放。

### `Model`

| 成员 | 说明 |
|---|---|
| `generate(prompt, **kw)` | 单轮生成，返回字符串 |
| `stream(prompt, **kw)` | 流式生成，逐段 yield |
| `session(system="")` | 开多轮会话，返回 `ChatSession` |
| `encode(text)` / `decode(id)` | 分词 / 反分词 |
| `set_threads(n)` / `threads` | 线程数 |
| `preload()` | 预加载权重 |
| `n_layers` / `d_model` / `vocab_size` / `max_seq_len` | 模型信息 |
| `chat_meta` | 模型内嵌的对话配置 |
| `close()` | 释放（`with` 会自动调） |

### `ChatSession`

| 成员 | 说明 |
|---|---|
| `chat(msg, **kw)` | 一轮对话，返回完整回答 |
| `stream(msg, **kw)` | 流式一轮 |
| `chat_with_prompt(msg)` | 返回 `(回答, 实际 prompt)`，排查格式用 |
| `history` | `[(q, a), ...]`，可直接改 |
| `clear()` | 清历史 + 重置 KV cache |
| `max_turns` | 进 prompt 的历史轮数（默认 8） |

### 生成参数（`**kw`）

| 参数 | 默认 | 说明 |
|---|---|---|
| `max_tokens` | 256 | 最大生成长度 |
| `temperature` | 0.6 | 随机性（0 = 贪心） |
| `top_k` | 40 | 前 K 个采样 |
| `top_p` | 0.9 | 核采样 |
| `min_p` | 0.0 | 最小概率阈值 |
| `min_tokens` | 4 | 至少生成 N 个 token 才允许停止（防空回复） |
| `repeat_penalty` | 1.05 | 重复惩罚 |
| `frequency_penalty` | 0.0 | 频率惩罚 |
| `dry_multiplier` | 0.8 | DRY 防复读强度 |
| `stop` | `None` | **自定义停止串**，如 `stop=["。", "<用户>"]` |
| `seed` | -1 | 随机种子（-1 = 随机） |

**参数优先级**：函数参数 > `.TG` 内嵌默认值 > 库内置默认值

---

## `.TG` 模型内嵌对话配置

`.TG` 文件可以自带对话模板，让库知道"怎么跟这个模型说话"。
第三方模型只要打包时带上配置，**不用改库的代码**。

```bash
# 查看配置
python -m tgai_go.tools.write_chat_meta model.TG --show

# 写内置预设: v27（TGAI 九标记） / chatml（Qwen2 等） / plain（纯文本）
python -m tgai_go.tools.write_chat_meta model.TG --preset v27
```

配置内容：

```
render_mode    markers | chatml | plain
chat_template  {SYS}{HIST}<用户>\n{Q}\n<TGAI>{TAIL}\n
template_turn  <用户>\n{Q}\n<TGAI><回答>\n{A}
special_tokens <用户> <TGAI> <思考> <回答> ...
turn_markers   <用户> <TGAI> <系统> ...     （生成到它即停）
stop_strings   ...                          （停止串）
gen_defaults   temperature=0.6 top_k=40 ...
```

只读查看（不加载权重，很快）：

```python
import tgai_go
print(tgai_go.chat_meta_of("v27.TG"))
```

---

## 内存

| 模型 | 权重（BF16） | 运行峰值 |
|---|---|---|
| TGAI V2.7（28 层 MoE） | 5.6 GB | 约 3.6 GB（开启 BF16 直算）|

`preload=True` 会额外占用（用于缓存解码后的权重），内存紧张时不要开。

---

## 常见问题

**Q: 生成结果是空的？**
调大 `min_tokens`（默认 4）。某些模型的首选 token 是停止符，不禁就会立即停。

**Q: 一直复读不停止？**
加自定义停止串：`m.generate(q, stop=["<用户>", "\n\n"])`。
或降低 `temperature`、调高 `dry_multiplier`。

**Q: 多轮对话记不住前文？**
检查 `.TG` 是否带对话配置（`tgai_go.chat_meta_of(path)`）。
没有配置时库会按 `arch_type` 猜，可能不匹配。

**Q: 加载很慢？**
首次加载要 mmap 权重。加 `preload=True` 把首次推理的卡顿提前。

**Q: 支持 GPU 吗？**
当前包是纯 CPU 引擎。GPU 桥接版本仍在验证（实测核显不如 CPU，
原因见主仓文档）。

---

## 从源码构建原生库（Linux/macOS）

```bash
git clone <repo>
cd "TGAI GO"
# Linux
gcc -O3 -fopenmp -mavx2 -shared -fPIC -o cpu/build/libtgai_engine.so \
    src/tgai_engine.c
# macOS
clang -O3 -Xpreprocessor -fopenmp -shared -o cpu/build/libtgai_engine.dylib \
    src/tgai_engine.c
```

然后把产物放到 `tgai_go/_native/`。

---

## License

MIT

---

## 相关

- `.TG` 格式：128 字节头 + 分词器段 + 权重表 + 权重数据（+ 可选对话配置段）
- 支持的架构：TGAI MoE / Llama / Mistral（按 `arch_type` 字段区分）
- 量化：FP32 / FP16 / BF16 / INT8 / Q8_0 / Q4_0 / Q4K
