ChatGLM-6B Gradio API对接：curl/postman调用方式与JSON Schema详解-平芜编程栈

ChatGLM-6B Gradio API对接：curl/postman调用方式与JSON Schema详解

1. 为什么需要直接调用API而不是只用Web界面

Gradio WebUI确实很友好，点点鼠标就能和ChatGLM-6B聊天。但实际工作中，你可能遇到这些情况：想把模型能力集成进自己的系统、需要批量处理上百条用户提问、要嵌入到企业微信或飞书机器人里、或者做自动化测试验证回答质量——这时候，光靠浏览器界面就不够用了。

本文不讲怎么点按钮，而是带你真正“打通”ChatGLM-6B的服务底层：用最常用的curl命令、Postman工具，像调用天气API一样调用这个大模型。你会看到完整的请求结构、每个参数的实际作用、返回数据的组织逻辑，甚至能一眼看懂官方JSON Schema文档在说什么。

所有操作都在已部署好的CSDN镜像上实测通过，不需要额外安装依赖，也不用改一行代码。

2. API服务基础认知：Gradio默认暴露的是什么

2.1 Gradio不是为API设计的，但可以被调用

很多人误以为Gradio只能做前端演示，其实它默认就提供了标准HTTP接口。当你启动服务并访问http://127.0.0.1:7860时，Gradio不仅渲染了网页，还在后台悄悄开启了两个关键端点：

http://127.0.0.1:7860/queue/join—— 用于提交任务（我们主要用这个）
http://127.0.0.1:7860/queue/data—— 用于轮询获取结果（自动完成，不用手动调）

但直接拼接这些URL太麻烦。Gradio更友好的方式是通过它的API文档页：打开http://127.0.0.1:7860/docs，你会看到一个Swagger风格的交互式API界面，里面列出了所有可用接口、参数说明和示例请求。

注意：这个/docs页面是Gradio自动生成的，不需要额外配置，只要服务跑起来就有。

2.2 实际可用的两种调用路径

调用方式	特点	适用场景
/api/predict（推荐）	简单直接，一次请求完成输入+等待+返回	小规模调用、脚本集成、快速验证
/queue/join + /queue/data	更接近Gradio原生队列机制，支持长任务、状态跟踪	高并发、需监控进度、超长文本生成

本文重点讲解第一种——/api/predict，因为它足够轻量、稳定、易理解，90%的业务需求都用它就够了。

3. curl命令调用实战：从零开始发第一个请求

3.1 准备工作：确认服务已就绪

先确保服务正在运行：

supervisorctl status chatglm-service

输出应为RUNNING。如果不是，请执行：

supervisorctl start chatglm-service

再检查日志确认无报错：

tail -n 20 /var/log/chatglm-service.log

看到类似Running on local URL: http://127.0.0.1:7860的日志，说明服务已就绪。

3.2 最简curl请求：三行搞定

打开终端，执行以下命令（假设你已通过SSH隧道将7860端口映射到本地）：

curl -X POST "http://127.0.0.1:7860/api/predict" \ -H "Content-Type: application/json" \ -d '{ "data": ["你好，你是谁？", null, null] }'

你将看到类似这样的响应：

{ "data": ["我是ChatGLM-6B，一个开源的中英双语对话模型。", null], "duration": 1245, "average_duration": 1245 }

成功了！这就是最基础的API调用。

3.3 参数详解：`data`数组里的三个位置代表什么

ChatGLM-6B的Gradio界面有三个输入控件：问题输入框、历史对话（隐藏）、参数设置（隐藏）。它们按顺序对应data数组的三个元素：

索引	字段名	类型	说明	示例
`0`	`query`	string	当前提问内容	`"今天北京天气怎么样？"`
`1`	`history`	array or null	对话历史，格式为`[["问1","答1"],["问2","答2"]]`	`[["你好","我是AI"],["吃饭了吗？","刚吃完"]]`
`2`	`params`	object or null	生成参数对象，含`temperature`、`top_p`等	`{"temperature": 0.7, "top_p": 0.9}`

关键提示：history和params可以传null，表示使用默认值；但query必须是非空字符串。

3.4 带历史和参数的完整请求示例

curl -X POST "http://127.0.0.1:7860/api/predict" \ -H "Content-Type: application/json" \ -d '{ "data": [ "你能帮我写一封辞职信吗？", [["上个月我入职了这家公司","是的"], ["我打算下个月离职","明白了"]], {"temperature": 0.5, "top_p": 0.85, "max_length": 1024} ] }'

这个请求模拟了真实多轮对话场景：用户已聊过两句，现在提出新需求，并希望回答更严谨（温度设为0.5）。

4. Postman调用指南：可视化调试更高效

4.1 创建新请求

打开Postman，点击「+ New」→「HTTP Request」
请求方法选POST
URL填http://127.0.0.1:7860/api/predict
切换到「Body」选项卡 → 选择「raw」→ 右侧下拉选JSON

4.2 构建请求体（同curl一致）

粘贴如下JSON（可直接复制）：

{ "data": [ "请用Python写一个计算斐波那契数列前10项的函数", null, { "temperature": 0.3, "top_p": 0.95, "repetition_penalty": 1.1 } ] }

4.3 发送并查看响应

点击「Send」后，右侧会显示响应体、状态码（应为200）、耗时等信息。你可以：

在「Pretty」模式下查看格式化JSON
切换到「Preview」看渲染后的文本效果
点击「Save Response」保存结果用于对比测试

小技巧：在Postman中右键响应体 → 「Copy Value」可快速复制生成的文本，方便粘贴到代码里。

5. JSON Schema深度解析：读懂官方接口定义

5.1 什么是JSON Schema？为什么它重要

JSON Schema是一种描述JSON数据结构的规范。它不是代码，而是一份“说明书”，告诉你：

这个API接受哪些字段？
每个字段是什么类型？是否必填？
取值范围是多少？（比如temperature必须在0.1~1.0之间）
哪些字段可以省略？

对于ChatGLM-6B的Gradio服务，Schema定义了/api/predict接口的全部契约。

5.2 核心Schema结构拆解（精简版）

以下是该服务实际暴露的JSON Schema关键部分（已去除冗余，保留实用字段）：

{ "type": "object", "properties": { "data": { "type": "array", "minItems": 3, "maxItems": 3, "items": [ { "type": "string", "description": "当前用户提问" }, { "oneOf": [ { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2 } }, { "type": "null" } ], "description": "对话历史，二维数组格式" }, { "oneOf": [ { "type": "object", "properties": { "temperature": { "type": "number", "minimum": 0.1, "maximum": 1.0, "default": 0.95 }, "top_p": { "type": "number", "minimum": 0.1, "maximum": 1.0, "default": 0.7 }, "max_length": { "type": "integer", "minimum": 128, "maximum": 2048, "default": 2048 }, "repetition_penalty": { "type": "number", "minimum": 1.0, "maximum": 2.0, "default": 1.1 } } }, { "type": "null" } ], "description": "生成参数配置" } ] } }, "required": ["data"] }

5.3 关键字段含义与实践建议

字段	含义	推荐值	注意事项
`temperature`	控制随机性	0.3~0.7（严谨任务） 0.8~1.0（创意任务）	值越低，回答越确定、重复性越高；过高可能导致胡言乱语
`top_p`	核采样阈值	0.85~0.95	和temperature配合使用，值越小，候选词越少，结果越集中
`max_length`	最大生成长度	512（短问答） 1024（长文） 2048（极限）	不是输入长度限制，而是模型最多输出多少token；设太高可能拖慢响应
`repetition_penalty`	重复惩罚	1.05~1.2	大于1.0可有效减少“嗯嗯嗯”、“是的是的”这类重复，但过高会抑制合理重复

实测经验：日常问答用{ "temperature": 0.7, "top_p": 0.9 }平衡效果最好；写代码或总结报告建议调低temperature至0.4~0.5。

6. 常见问题与排错指南

6.1 HTTP 422 Unprocessable Entity 错误

这是最常见的报错，通常因为JSON格式错误或字段类型不符。典型原因：

data数组长度不是3个元素（必须是3个！）
query字段为空字符串""或null
history数组里某一对不是[str, str]，比如写了["问", 123]
params里传了不存在的字段，如"num_beams": 4

解决方法：用在线JSON校验工具（如 jsonlint.com）粘贴你的请求体，检查语法；再对照上一节的Schema核对字段类型。

6.2 响应超时（HTTP 504 Gateway Timeout）

Gradio默认超时是60秒。如果生成内容特别长（如写一篇2000字文章），可能超时。

解决方法：

提高max_length同时降低temperature，让模型更快收敛；
在params中加入"timeout": 120（部分Gradio版本支持）；
改用/queue/join方式，它天然支持长任务。

6.3 返回内容含多余HTML标签或换行符

这是Gradio WebUI渲染导致的副作用。原始响应中的data[0]是纯文本，但有时会包含\n或<br>。

清洗建议（Python示例）：

import re def clean_response(text): # 去除首尾空白，合并连续换行 text = re.sub(r'\n+', '\n', text.strip()) # 去除可能的HTML标签（Gradio偶尔注入） text = re.sub(r'<[^>]+>', '', text) return text # 使用 raw_text = response_json["data"][0] clean_text = clean_response(raw_text)

7. 进阶技巧：构建生产级调用封装

7.1 用Python封装成简洁函数

把重复的curl逻辑封装成函数，提升复用性：

import requests import time def chatglm_api(query, history=None, params=None, base_url="http://127.0.0.1:7860"): """ 调用ChatGLM-6B Gradio API :param query: 当前问题（字符串） :param history: 对话历史列表，如[["问1","答1"]] :param params: 参数字典，如{"temperature": 0.7} :param base_url: 服务地址 :return: 模型回答字符串 """ url = f"{base_url}/api/predict" payload = { "data": [ query, history or None, params or None ] } try: resp = requests.post(url, json=payload, timeout=60) resp.raise_for_status() result = resp.json() return result["data"][0].strip() except requests.exceptions.RequestException as e: print(f"请求失败: {e}") return "" # 使用示例 answer = chatglm_api( query="请解释Transformer架构的核心思想", params={"temperature": 0.5, "max_length": 1024} ) print(answer)

7.2 批量处理：一次发送多个问题

虽然Gradio单次只处理一个问题，但你可以用循环+异步请求实现批量：

import asyncio import aiohttp async def batch_chat(queries, session, base_url="http://127.0.0.1:7860"): tasks = [] for q in queries: task = asyncio.create_task( session.post( f"{base_url}/api/predict", json={"data": [q, None, None]} ) ) tasks.append(task) results = await asyncio.gather(*tasks) return [r.json()["data"][0] for r in results if r.status == 200] # 运行 queries = ["什么是机器学习？", "监督学习和无监督学习区别？", "举个强化学习例子"] async with aiohttp.ClientSession() as session: answers = await batch_chat(queries, session)

8. 总结：掌握API就是掌握主动权

Gradio WebUI是入口，API才是真正的控制台。当你能用curl发请求、用Postman调试、读懂JSON Schema、写出健壮的封装函数时，你就不再是一个被动使用者，而是这个智能对话能力的集成者和调度者。

本文覆盖了从最简调用到生产封装的全链路：

三行curl发出第一个请求
Postman可视化调试技巧
JSON Schema逐字段解读与避坑指南
四类高频报错的定位与解决
Python函数封装与异步批量处理

下一步，你可以尝试：

把这个API接入钉钉机器人，让团队随时提问
结合RAG技术，给模型注入公司内部知识
用Prometheus监控API延迟与成功率

能力已经就绪，剩下的只是你想把它用在哪里。

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

ChatGLM-6B Gradio API对接：curl/postman调用方式与JSON Schema详解