tgai-go 1.0.0__tar.gz

tgai_go-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TGAI / JXW
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tgai_go-1.0.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: tgai-go
+Version: 1.0.0
+Summary: TGAI GO —— 纯 Python 的 TGAI 模型推理库（CPU 引擎，零编译安装）
+Author: TGAI
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tgai/tgai-go
+Project-URL: Documentation, https://github.com/tgai/tgai-go#readme
+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 需自行编译原生库（见文末）。
+
+---
+
+## 快速开始
+
+### 单轮生成
+
+```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 线程  →  7.7 tok/s
+#   8 线程  → 12.0 tok/s   ← 最优
+#  16 线程  → 10.7 tok/s   （超线程反而变慢）
+```
+
+---
+
+## 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

tgai_go-1.0.0/README.md

@@ -0,0 +1,235 @@
+# 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 需自行编译原生库（见文末）。
+
+---
+
+## 快速开始
+
+### 单轮生成
+
+```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 线程  →  7.7 tok/s
+#   8 线程  → 12.0 tok/s   ← 最优
+#  16 线程  → 10.7 tok/s   （超线程反而变慢）
+```
+
+---
+
+## 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

tgai_go-1.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tgai-go"
+version = "1.0.0"
+description = "TGAI GO —— 纯 Python 的 TGAI 模型推理库（CPU 引擎，零编译安装）"
+readme = "README.md"
+requires-python = ">=3.8"
+# ★ license 用 SPDX 字符串（2026-10-11 改）
+#   原来写的是 license = { text = "MIT" }（TOML 表形式），
+#   setuptools >= 77 已弃用，构建时会刷一大段警告并声明
+#   2027-02-18 后不再支持。改成 SPDX 表达式即可（加 license-files 更规范）。
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "TGAI" }]
+keywords = ["tgai", "llm", "inference", "moe", "chinese", "llama"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    # 只有 numpy：采样与张量运算用
+    "numpy>=1.20",
+]
+
+[project.optional-dependencies]
+# 外部分词器（大词表模型的兜底方案；不装也能跑内置分词器）
+tokenizer = ["tokenizers>=0.15"]
+# 开发/测试
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/tgai/tgai-go"
+Documentation = "https://github.com/tgai/tgai-go#readme"
+
+[project.scripts]
+# 命令行入口（可选）：tgai-go chat -m model.TG
+# 注意这只是薄封装，主要用法是 import tgai_go
+tgai-go = "tgai_go.__main__:main"
+
+[tool.setuptools]
+# ★ _native 必须显式列出（2026-10-11 修）
+#   它是只装 .dll 的数据目录、没有 __init__.py，但仍被 Python 视为
+#   "可导入的包"。只写 packages = ["tgai_go"] 时 setuptools 会警告：
+#     Package 'tgai_go._native' is absent from the `packages` configuration
+#     -> Package would be ignored
+#   虽然实测 DLL 仍被打进 wheel（靠 package-data），但该警告属"配置含糊"，
+#   随时可能在某个 setuptools 版本变成真的丢文件。显式列出最稳。
+packages = ["tgai_go", "tgai_go._native"]
+include-package-data = true
+zip-safe = false
+
+[tool.setuptools.package-data]
+# ★ 原生引擎随包分发：用户 pip install 后无需编译
+#   文件名由 build_wheel.py 按平台放置
+"tgai_go" = ["_native/*.dll", "_native/*.so", "_native/*.dylib", "_native/README.md"]
+
+[tool.setuptools.exclude-package-data]
+"*" = ["*.pyc", "__pycache__/*", "*.c", "*.obj", "*.lib", "*.exp"]

tgai_go-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+