Metadata-Version: 2.4
Name: glm-client
Version: 0.3.0
Summary: GLM (智谱AI) 大模型 Python 客户端库 - 支持文本生成、OCR 文字识别、视觉理解、图像生成、语音合成、视频生成、文本嵌入等
Project-URL: Homepage, https://github.com/fengrui358/GLM-API
Project-URL: Documentation, https://github.com/fengrui358/GLM-API#readme
Project-URL: Repository, https://github.com/fengrui358/GLM-API
Project-URL: Issues, https://github.com/fengrui358/GLM-API/issues
Project-URL: Changelog, https://github.com/fengrui358/GLM-API/blob/main/CHANGELOG.md
Author-email: fengrui <fengrui@163.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,chatgpt,chinese-ai,document-summary,embedding,file-management,glm,image-generation,image-to-text,llm,ocr,pdf-ocr,speech-recognition,text-extraction,text-generation,tts,video-generation,vision,zhipu,zhipuai
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydub>=0.25.1
Requires-Dist: pypdf2>=3.0.1
Requires-Dist: python-docx>=1.2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: sniffio>=1.3.1
Requires-Dist: typer>=0.12.0
Requires-Dist: zai-sdk>=0.0.3
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.24.0; extra == 'pdf'
Description-Content-Type: text/markdown

# GLM Client

智谱AI GLM 大模型 Python 客户端库 —— 支持文本生成、OCR 文字识别、视觉理解、图像生成、语音合成、视频生成、文本嵌入、语音识别等多模态能力。

## 特性

- **OCR 文字识别**：图片/PDF 文字提取，支持本地文件和 URL，免费模型驱动
- **文本生成**：流式/非流式聊天补全，支持思考模式和联网搜索
- **视觉理解**：图像分析、多图比较、批量分析
- **图像生成**：基于 CogView 的文生图
- **语音合成**：多音色 TTS，支持 Word 文档转语音
- **视频生成**：文本/图片生成视频
- **文本嵌入**：向量生成和相似度计算
- **语音识别**：音频转文字
- **自动重试**：指数退避重试机制
- **双 SDK 支持**：优先使用 `zai-sdk`，兼容旧版 `zhipuai`

## 快速开始

### 安装

```bash
# 基础安装（图片 OCR）
pip install glm-client

# 包含 PDF 支持的安装
pip install "glm-client[pdf]"
```

### 配置

获取 API Key：[https://open.bigmodel.cn/](https://open.bigmodel.cn/)

```bash
# 方法一：环境变量
export ZAI_API_KEY="your_api_key_here"

# 方法二：.env 文件
echo 'ZAI_API_KEY=your_api_key_here' > .env
```

### 30 秒上手

```python
from glm_client import GLMClient, chat_completion

client = GLMClient()

# 流式对话
response = chat_completion("你好，介绍一下你自己", client=client, stream=True)
for chunk in response:
    print(chunk, end="")
```

或使用命令行：

```bash
glm-client chat "你好，介绍一下你自己"
```

## 免费模型推荐

基于[基准测试](docs/benchmark_summarize_ocr.md)的免费模型推荐：

| 能力 | 推荐模型 | 价格 | 上下文 |
|------|---------|------|--------|
| 文本对话 / 摘要 | `glm-4-flash` | **永久免费** | 128K |
| **OCR 识别** | **`glm-4v-flash`** | **永久免费** | - |
| 视觉理解 | `glm-4v-flash` | **永久免费** | - |
| 图像生成 | `cogview-3-flash` | 付费 | - |
| 语音合成 | `glm-tts` | 付费 | - |
| 视频生成 | `cogvideox-2` | 付费 | - |
| 文本嵌入 | `embedding-3` | 付费 | 8K |
| 语音识别 | `glm-asr` | 付费 | - |

> 新用户注册即获 2000 万 token 免费额度，推荐使用免费模型进行开发测试。

## 功能详解

### OCR 文字识别

基于 GLM-4V-Flash 视觉模型的 OCR 能力，支持图片和 PDF 文件的文字提取，**完全免费**。

#### 基础用法

```python
from glm_client import GLMClient, ocr

client = GLMClient()

# 识别本地图片
text = ocr("invoice.jpg", client=client)
print(text)

# 识别网络图片
text = ocr("https://example.com/screenshot.png", client=client)

# 识别 PDF 文件（需要 pip install "glm-client[pdf]"）
text = ocr("contract.pdf", client=client)

# 识别网络 PDF
text = ocr("https://example.com/document.pdf", client=client)
```

#### 批量识别

```python
from glm_client import GLMClient, ocr_batch

client = GLMClient()

results = ocr_batch(
    ["page1.jpg", "page2.png", "page3.jpg"],
    client=client,
    verbose=True,  # 显示处理进度
)

for path, text in zip(["page1.jpg", "page2.png", "page3.jpg"], results):
    print(f"=== {path} ===")
    print(text)
```

#### 自定义参数

```python
from glm_client import GLMClient, ocr

client = GLMClient()

# 自定义 OCR 提示词（适用于特定场景）
text = ocr(
    "receipt.jpg",
    client=client,
    prompt="请提取这张发票中的金额、日期、商品名称，以 JSON 格式输出",
)

# 调整 PDF 渲染精度（默认 200，提高可获得更好识别效果）
text = ocr(
    "document.pdf",
    client=client,
    dpi=300,
    max_tokens=8192,
)

# 使用其他视觉模型
text = ocr("photo.jpg", client=client, model="glm-4.6v-flash")
```

#### API 参考

**`ocr(source, client, ...)`** — 识别单个文件

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `source` | `str \| Path` | 必填 | 图片/PDF 文件路径或 URL |
| `client` | `GLMClient` | 必填 | GLM 客户端实例 |
| `model` | `str` | `glm-4v-flash` | 视觉模型名称 |
| `prompt` | `str` | 内置 OCR prompt | 自定义识别提示词 |
| `max_tokens` | `int` | `4096` | 最大输出 token 数 |
| `temperature` | `float` | `0.1` | 采样温度 |
| `dpi` | `int` | `200` | PDF 渲染分辨率 |
| `page_separator` | `str` | 含页码的分隔符 | PDF 多页分隔符模板 |
| `verbose` | `bool` | `False` | 是否显示处理进度 |

**`ocr_batch(sources, client, ...)`** — 批量识别多个文件

参数与 `ocr()` 类似，`sources` 为文件路径/URL 列表，返回对应的结果列表。

#### 支持的文件类型

| 类型 | 格式 | 说明 |
|------|------|------|
| 图片 | jpg, jpeg, png, gif, webp, bmp | 本地文件或 URL |
| PDF | pdf | 需要安装 `pymupdf`（`pip install "glm-client[pdf]"`） |

### 文档摘要

基于最强免费文本模型 `glm-4-flash`，对文档内容生成结构化摘要，输出统一 JSON 格式，适用于文件管理、搜索和分类。

#### 基础用法

```python
from glm_client import GLMClient, summarize

client = GLMClient()

# 对文本内容生成摘要
result = summarize("合同全文内容...", client=client)

print(result.title)          # 文档标题
print(result.document_type)  # "合同" / "方案" / "报告" ...
print(result.summary)        # 核心摘要（200 字以内）
print(result.keywords)       # ["关键词1", "关键词2", ...]
print(result.key_info)       # {"dates": [...], "parties": [...], "amounts": [...]}

# 导出为 dict 或 JSON
result.to_dict()
result.to_json()
```

#### 直接传入文件

```python
from glm_client import GLMClient, summarize_file

client = GLMClient()

# 自动 OCR + 摘要（支持图片和 PDF）
result = summarize_file("contract.pdf", client=client, verbose=True)
print(result.to_json())
```

#### 输出结构

`summarize()` 和 `summarize_file()` 返回 `DocumentSummary` 对象，包含以下字段：

| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `title` | `str` | 文档标题 | `"XX公司技术服务合同"` |
| `document_type` | `str` | 文件类型 | `"合同"` |
| `category` | `str` | 业务分类 | `"法务"` |
| `summary` | `str` | 核心摘要（≤200 字） | `"甲方委托乙方提供..."` |
| `keywords` | `list[str]` | 关键词（最多 5 个） | `["技术服务", "合同"]` |
| `key_info` | `dict` | 关键信息 | `{"dates": [...], "parties": [...]}` |
| `language` | `str` | 主要语言 | `"zh"` |
| `confidence` | `str` | 置信度 | `"high"` |

`document_type` 可选值：合同、协议、方案、报告、通知、简历、发票、收据、证书、规章制度、会议纪要、邮件、论文、说明书、其他。

#### 与文件管理系统集成示例

```python
from glm_client import GLMClient, summarize_file

client = GLMClient()

def index_document(file_path: str) -> dict:
    """扫描文件并生成索引，存入数据库。"""
    result = summarize_file(file_path, client=client)
    return {
        "file_path": file_path,
        "title": result.title,
        "doc_type": result.document_type,
        "summary": result.summary,
        "keywords": ", ".join(result.keywords),
        "parties": ", ".join(result.key_info.get("parties", [])),
        "dates": ", ".join(result.key_info.get("dates", [])),
        "metadata_json": result.to_json(),
    }

# 批量索引
for doc in ["contract.pdf", "proposal.docx_scan.jpg", "report.pdf"]:
    entry = index_document(doc)
    # db.insert(entry)  # 存入你的数据库
    print(entry["title"], entry["keywords"])
```

### 文本生成

```bash
# 基础对话
glm-client chat "解释量子计算"

# 交互模式
glm-client chat -i

# 启用思考模式（需支持思考的模型）
glm-client chat "解一道复杂的数学题" --thinking

# 启用联网搜索
glm-client chat "今天的新闻" --web-search

# 自定义参数
glm-client chat "写一首诗" --temperature 0.9 --no-stream
```

```python
from glm_client import GLMClient, chat_completion

client = GLMClient()

# 非流式
response = chat_completion("你好", client=client, stream=False)
print(response)

# 流式
for chunk in chat_completion("你好", client=client, stream=True):
    print(chunk, end="")

# 多轮对话
history = [{"role": "user", "content": "我叫小明"}, {"role": "assistant", "content": "你好小明！"}]
response = chat_completion("我叫什么名字？", client=client, history=history, stream=False)
```

### 视觉理解

```bash
glm-client vision "描述这张图片" --image photo.jpg
glm-client vision "图中有什么？" --image-url "https://example.com/image.jpg"
```

```python
from glm_client import vision_completion, compare_images

result = vision_completion("描述图片内容", "photo.jpg", client=client)
print(result)

# 多图比较
result = compare_images("比较这两张图片的区别", ["img1.jpg", "img2.jpg"], client=client)
```

### 图像生成

```bash
glm-client image "一只坐在桌上的猫"
glm-client image "日落" --output sunset.png --size 1024x1024
```

```python
from glm_client import generate_image, generate_and_save

urls = generate_image("一只猫", client=client)
paths = generate_and_save("一只猫", client=client, output="output/")
```

### 语音合成

```bash
glm-client tts "你好，世界！"
glm-client tts --word document.docx --output audio.wav
glm-client tts "测试" --voice chen --format mp3
```

```python
from glm_client import text_to_speech, word_to_speech

path = text_to_speech("你好", client=client, voice="female")
path = word_to_speech("doc.docx", client=client)
```

可用音色：`female`（彤彤，默认）、`chen`（小陈）、`cuicui`（锤锤）、`jam`、`kazi`、`douji`、`luodo`

### 视频生成

```bash
glm-client video "一只猫在玩球"
glm-client video "让画面动起来" --image-url "https://example.com/image.jpg"
glm-client video "日落海滩" --output sunset.mp4 --fps 60
```

```python
from glm_client import generate_video, generate_and_save_video

url = generate_video("一只猫在玩球", client=client)
path = generate_and_save_video("一只猫在玩球", client=client, output="video.mp4")
```

### 文本嵌入

```bash
glm-client embed "人工智能"
glm-client embed "机器学习" --compare "深度学习"
```

```python
from glm_client import create_embedding, compute_similarity

vector = create_embedding("人工智能", client=client)
score = compute_similarity("机器学习", "深度学习", client=client)
print(f"相似度: {score:.4f}")
```

### 语音识别

```bash
glm-client asr --file audio.wav
glm-client asr -f recording.mp3 --language zh
```

```python
from glm_client import transcribe_audio

text = transcribe_audio("audio.wav", client=client)
print(text)
```

## CLI 命令参考

| 命令 | 说明 | 示例 |
|------|------|------|
| `chat` | 文本生成 | `glm-client chat "你好"` |
| `vision` | 图像分析 | `glm-client vision "描述" -i img.jpg` |
| `image` | 图像生成 | `glm-client image "一只猫"` |
| `tts` | 语音合成 | `glm-client tts "你好"` |
| `video` | 视频生成 | `glm-client video "日落"` |
| `embed` | 文本嵌入 | `glm-client embed "文本"` |
| `asr` | 语音识别 | `glm-client asr -f audio.wav` |
| `config` | 配置管理 | `glm-client config --list-models` |

> **OCR 提示**：OCR 功能目前仅通过 Python API 提供（`ocr()` / `ocr_batch()`），CLI 命令支持即将推出。

## 作为库使用

```python
from glm_client import (
    GLMClient,
    chat_completion,
    ocr,
    ocr_batch,
    summarize,
    summarize_file,
    vision_completion,
    generate_image,
    text_to_speech,
    generate_video,
    create_embedding,
    transcribe_audio,
)

client = GLMClient()

# 文本
response = chat_completion("你好", client=client, stream=False)

# OCR 文字识别
text = ocr("invoice.jpg", client=client)
text = ocr("contract.pdf", client=client)

# 文档摘要（结构化 JSON 输出）
result = summarize("文档内容...", client=client)
print(result.title, result.keywords)

# 文件直接摘要（OCR + 摘要一步到位）
result = summarize_file("contract.pdf", client=client)

# 视觉
result = vision_completion("描述图片", "photo.jpg", client=client)

# 图像生成
urls = generate_image("日落", client=client)

# 嵌入
vector = create_embedding("测试文本", client=client)
```

## 开发

```bash
# 安装开发依赖
uv sync

# 运行测试
uv run pytest tests/

# 运行集成测试（需要真实 API Key）
uv run pytest -m integration

# 运行基准测试
uv run python scripts/benchmark_summarize_ocr.py

# 构建包
uv build
```

## 常见问题

**Q: 认证失败？**
确保设置了 `ZAI_API_KEY` 或 `ZHIPUAI_API_KEY` 环境变量。

**Q: 速率限制？**
客户端内置自动重试机制（指数退避），请等待后重试。

**Q: 模型不存在？**
使用 `glm-client config --list-models` 查看所有可用模型。

## 许可证

MIT License - 详见 [LICENSE](LICENSE)

## 参考

- [官方 SDK 文档](https://docs.bigmodel.cn/cn/guide/develop/python/introduction)
- [API 定价](https://open.bigmodel.cn/pricing)
- [zai-sdk GitHub](https://github.com/zai-org/z-ai-sdk-python)
- [zhipuai-sdk GitHub](https://github.com/MetaGLM/zhipuai-sdk-python-v4)
