Python入门实战：调用GLM-OCR API完成你的第一个文字识别程序

你是不是经常看到一些图片里的文字，觉得手动敲下来太麻烦？或者想写个小程序，自动把截图里的信息提取出来？今天，我们就来动手做一个这样的小工具。不需要你懂复杂的图像处理算法，也不用搭建庞大的本地环境。我们直接调用一个已经部署好的文字识别服务，用Python写一个简单的脚本，就能轻松搞定。

这篇文章就是为你准备的，如果你刚接触Python，想通过一个有趣又实用的项目来练手，那就再合适不过了。整个过程就像搭积木一样简单：准备一张图片，写几行代码发送请求，然后就能拿到识别出来的文字。我会手把手带你走完每一步，从安装必要的库开始，到最终把识别结果保存成文件。学完这个，你不仅能掌握调用网络API的基本方法，还能收获一个马上就能用起来的小工具，成就感满满。

1. 准备工作：搭建你的Python环境

在开始写代码之前，我们需要确保电脑上已经准备好了“工具箱”。别担心，步骤非常简单。

1.1 确认Python已经安装

首先，打开你的命令行工具。在Windows上可以搜索“cmd”或“PowerShell”，在Mac或Linux上打开“终端”。然后输入下面的命令并回车：

python --version

或者试试：

python3 --version

如果屏幕上显示了类似 Python 3.8.10 这样的版本号，恭喜你，Python已经就位。如果提示“找不到命令”，那你需要先去Python官网下载并安装最新版本，安装时记得勾选“Add Python to PATH”这个选项。

1.2 安装必需的requests库

我们的程序需要通过互联网与文字识别服务“对话”，而 requests 库就是Python里最擅长做这件事的工具。安装它只需要一行命令。

在刚才打开的命令行里，输入：

pip install requests

如果上面的命令因为权限问题失败了，可以尝试加上 --user 参数：

pip install --user requests

看到类似“Successfully installed requests-2.31.0”的提示，就说明安装成功了。

1.3 准备一张测试图片

接下来，找一张包含清晰文字的图片。可以是：

• 书本的一页照片（确保光线均匀）
• 电脑屏幕的截图（比如一段新闻或文档）
• 一张清晰的路牌或海报照片

把这张图片保存下来，记住它的存放位置。为了后续代码编写方便，我建议你把它放在一个容易找到的文件夹里，比如在桌面新建一个叫 ocr_project 的文件夹，然后把图片放进去。我们假设这张图片的名字叫 test_image.jpg。

2. 理解核心：API是什么以及如何工作

在动手写代码前，花两分钟了解一下我们要做的事情背后的原理，这样你会更清楚每一步在干什么。

你可以把我们要调用的GLM-OCR服务想象成一个在远方的“文字识别专家”。我们的程序（客户端）和这位专家（服务端）之间，需要一种标准的沟通方式，这就是API（应用程序编程接口）。

整个过程分为三步：

1. 我们发送请求：我们把本地图片打包，附上我们的“问题”（即调用指令），通过互联网发送给服务端。
2. 专家处理并回答：服务端的“专家”收到图片后，动用它的模型能力识别其中的文字。
3. 我们接收结果：专家将识别出的文字整理好，打包成一个格式规范的“回信”（通常是JSON格式），再通过网络传回给我们。

我们写的Python脚本，就是负责第一步和第三步：组织请求和解析结果。而最复杂的识别过程，则由云端强大的模型替我们完成了。这种模式让我们能用很少的代码，实现很复杂的功能。

3. 分步实战：编写你的第一个OCR脚本

现在，打开你喜欢的代码编辑器（比如VS Code、PyCharm，甚至系统的记事本也可以），我们开始一步步构建完整的程序。

3.1 创建Python文件并导入库

在你的项目文件夹（比如刚才说的 ocr_project）里，新建一个文件，命名为 my_first_ocr.py。然后在文件的最开头，写下这行代码：

import requests
import json

• import requests：这就是我们刚才安装的库，用来发送网络请求。
• import json：这是Python自带的库，用来处理API返回的JSON格式数据，把它转换成Python里容易操作的字典或列表。

3.2 设置API的访问地址和密钥

调用任何API通常都需要两个关键信息：服务地址和通行证（API Key）。这里我们需要根据服务提供商（星图GPU平台）的说明来填写。

# 配置API信息
api_url = "https://your-glm-ocr-service-endpoint.com/v1/ocr"  # 请替换为实际的API端点
api_key = "your_actual_api_key_here"  # 请替换为你自己的API密钥

# 准备请求头，告诉服务器我们的身份和发送的数据格式
headers = {
    "Authorization": f"Bearer {api_key}",  # 通常用这种格式传递密钥
    "Content-Type": "application/json"     # 告诉服务器我们发送的是JSON数据
}

重要提示：

• api_url：这个地址需要你替换成GLM-OCR服务在星图GPU平台上部署后提供的真实访问地址。通常在服务部署成功的页面可以找到。
• api_key：这是你的个人密钥，相当于密码，用于验证身份。同样需要在平台的管理界面获取。
• 请务必保管好你的 api_key，不要把它直接上传到公开的代码仓库（如GitHub）。

3.3 读取本地图片并准备请求数据

我们的图片是二进制文件，需要以特定的方式读入并编码，才能放在JSON请求体中发送。

# 指定你要识别的图片路径
image_path = "test_image.jpg"  # 确保图片文件在当前目录下，或使用完整路径如 "C:/Users/.../test_image.jpg"

# 以二进制模式读取图片文件
with open(image_path, 'rb') as image_file:
    image_data = image_file.read()

# 将二进制图片数据进行Base64编码，使其可以安全地放入JSON文本中
import base64
image_base64 = base64.b64encode(image_data).decode('utf-8')

# 构造请求体，这是一个字典，最终会被转换成JSON字符串
payload = {
    "image": image_base64,  # 将编码后的图片数据放入
    "task": "general"       # 指定任务类型，这里用通用识别。有些API可能还有其他选项如`document`(文档)
}

这里用到了 base64 编码，这是一种将二进制数据（如图片）转换成纯文本字符串的方法，这样它才能被安全地包裹在JSON这种文本格式中传输。

3.4 发送POST请求并获取响应

这是最核心的一步，我们使用 requests 库将准备好的数据发送出去。

try:
    # 发送POST请求到API地址，附带请求头和JSON格式的数据
    response = requests.post(api_url, headers=headers, json=payload)
    
    # 检查HTTP请求是否成功（状态码200表示成功）
    response.raise_for_status()  
    
    # 将服务器返回的JSON字符串解析为Python字典
    result = response.json()
    
    print("API请求成功！")
    
except requests.exceptions.RequestException as e:
    # 处理网络请求错误（如超时、连接失败）
    print(f"网络请求出错: {e}")
    exit(1)
except ValueError as e:
    # 处理响应内容不是合法JSON的错误
    print(f"解析JSON响应出错: {e}")
    print(f"原始响应内容: {response.text}")
    exit(1)

我们用了 try...except 来捕获可能出现的错误，比如网络不好、地址写错了、或者密钥无效。这样程序就不会因为一个错误而直接崩溃，而是会友好地告诉你问题出在哪里。

3.5 解析结果并提取文字

API成功返回后，数据会存储在 result 变量里。我们需要知道它的结构，才能从中提取出我们想要的文字。

# 解析识别结果。不同API返回的JSON结构可能略有不同，请根据实际返回调整。
# 常见的结构是有一个 `text` 字段，或者一个包含多个文本块的 `blocks` 列表。
if 'text' in result:
    # 如果结果中直接包含拼接好的全文
    all_text = result['text']
    print("识别出的全文如下：")
    print("-" * 30)
    print(all_text)
    print("-" * 30)
    
elif 'blocks' in result:
    # 如果结果是按文本块返回的（包含位置和文字）
    all_text = ""
    print("识别结果（按文本块）：")
    print("-" * 30)
    for idx, block in enumerate(result['blocks'], 1):
        block_text = block.get('text', '')
        print(f"块 {idx}: {block_text}")
        all_text += block_text + "\n"  # 将每个块的文字拼接起来，用换行符分隔
    print("-" * 30)
    
else:
    # 如果返回结构不符合预期，打印出来看看
    print("未找到预期的'text'或'blocks'字段。完整的API返回是：")
    print(json.dumps(result, indent=2, ensure_ascii=False))
    all_text = ""

这部分代码展示了两种常见的API返回格式。最理想的情况是直接拿到拼接好的 all_text。你可以运行后，根据打印出的完整结果来调整提取逻辑。

3.6 将识别结果保存到文件

拿到文字后，我们把它保存到本地的一个文本文件中，方便以后查看和使用。

# 定义输出文件名
output_filename = "recognized_text.txt"

# 将识别出的文字写入文本文件
try:
    with open(output_filename, 'w', encoding='utf-8') as f:
        f.write(all_text)
    print(f"\n识别结果已成功保存到文件: {output_filename}")
except IOError as e:
    print(f"写入文件时出错: {e}")

使用 encoding='utf-8' 可以确保中文等非英文字符能正确保存，不会出现乱码。

4. 运行与调试：让程序跑起来

脚本写完了，现在让我们来运行它，看看效果。

4.1 运行脚本

回到命令行，确保当前目录是你的项目文件夹（包含 my_first_ocr.py 和 test_image.jpg），然后运行：

python my_first_ocr.py

如果一切顺利，你会在命令行里看到打印出的识别文字，同时当前文件夹下会生成一个 recognized_text.txt 文件，里面就是完整的结果。

4.2 常见问题与解决

第一次运行很可能不会那么完美，下面是一些你可能会遇到的问题及解决方法：

• 问题：ModuleNotFoundError: No module named 'requests'

  • 原因：requests库没有安装成功或安装在了其他Python环境。
  • 解决：回到1.2节，确认安装命令执行成功。如果你有多个Python版本，确保你用的 pip 和 python 命令属于同一个版本。

• 问题：requests.exceptions.ConnectionError 或超时

  • 原因：网络连接问题，或者 api_url 地址填写错误。
  • 解决：检查网络是否通畅。仔细核对 api_url 是否完全按照服务提供商给的地址填写，一个字符都不能错。

• 问题：401 Unauthorized 或 403 Forbidden

  • 原因：API密钥（api_key）无效、过期或没有权限。
  • 解决：登录星图GPU平台，确认你的API密钥是否正确，以及该密钥是否有权限调用OCR服务。

• 问题：识别结果为空或乱码

  • 原因：图片不清晰、光线太暗、文字太小或字体特殊；或者返回结果解析逻辑不对。
  • 解决：换一张清晰、文字明显的图片试试。打印出完整的 result（参考3.5节最后的代码），查看实际返回的数据结构，然后调整解析文字的代码。

5. 更进一步：优化你的小程序

基础功能实现后，我们可以让它变得更强大、更好用。这里有几个简单的扩展思路：

1. 支持多张图片批量识别 你可以修改程序，让它读取一个文件夹里的所有图片，然后一张一张地识别，最后把所有的文字合并到一个文件里，或者为每张图片单独生成一个结果文件。

2. 添加简单的图片预处理 有时候图片有点歪，会影响识别。你可以引入一个叫 PIL（Pillow库）的图片处理库，在发送前先自动把图片旋转摆正，或者调整一下对比度，这样可能会提高识别准确率。

3. 制作成带界面的小工具 如果你觉得命令行不够直观，可以学习使用 tkinter（Python自带的库）来做一个简单的桌面窗口。在窗口上添加一个按钮来选择图片，再添加一个文本框来直接显示识别结果，用起来会更方便。

4. 处理更复杂的返回结果 有些高级的OCR API不仅能返回文字，还能告诉你每个字在图片上的具体位置（坐标）。你可以利用这些坐标信息，在图片上画出文字所在的矩形框，生成一个“可视化”的结果图，这对于检查识别准确性很有帮助。

整个项目做下来，感觉还是挺顺畅的。核心其实就是那么几步：准备好图片和密钥，用requests库把数据送出去，再把返回的JSON结果解析出来。对于Python新手来说，这是一个非常好的练手项目，它串联起了文件操作、网络请求、数据解析这几个基础又重要的技能点。

最关键的是，你做出了一个真正有用的小工具。下次再需要从图片里摘文字，就不用再手动敲键盘了。如果你在运行过程中卡在了某一步，别着急，回头仔细检查一下代码里的网址和密钥是不是填对了，这是最容易出错的地方。成功运行一次之后，你可以试着换不同的图片玩玩，看看它的识别能力到底怎么样。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。