用 Cohere Chat 接口构建入职助手：提示词、参数与结构化输出

Cohere 的 Command 系列模型面向实际业务场景设计，擅长摘要、文案撰写、信息抽取和问答这类任务。要通过代码调用这些模型，入口是 Chat 接口：传入模型 ID 和消息列表，就能拿到模型生成的文本。本文以「为新员工搭建一个入职助手」为主线，把从安装客户端到流式输出的完整链路走一遍，包括基础文本生成、提示词写法、输出参数调节、结构化 JSON 输出和流式响应。如果你更想先在浏览器里试一下效果，可以打开 Cohere 的工具页了解入口，再回到代码里实现。

本文适合已经会写一点 Python、准备把大模型接进自己业务系统的开发者。所有示例都围绕同一个场景展开，方便你对照着改造成自己的用例。

准备工作

开始之前需要准备三样东西：一个可用的 Cohere 账号与 API Key、Python 环境、以及 cohere 官方 SDK。

• API Key：在 Cohere 的控制台里创建。示例代码里用占位符 COHERE_API_KEY 表示，实际运行时替换成你自己的密钥，不要把它硬编码进提交到版本库的文件里。
• Python 环境：能运行 Python 3 即可，建议在虚拟环境里安装依赖，避免和其他项目的包版本冲突。
• cohere SDK：通过 pip 安装，命令如下。

pip install cohere

安装完成后，创建客户端对象。本文所有示例都使用 v2 版本的客户端 ClientV2，它对应 Chat 接口的 v2 版本。

import cohere
import json

co = cohere.ClientV2(api_key="COHERE_API_KEY")

这里的 co 就是后续所有调用的入口。注意 json 模块也一并导入，后面处理结构化输出时会用到。

操作步骤

第一步：发起一次最基础的文本生成

Chat 接口最少需要两个参数：model 指定模型 ID，messages 传入消息列表。消息列表里每个元素是一个字典，包含 role 和 content 两个字段；最简场景下只有一条 role 为 user 的消息。

下面让模型帮一位即将入职的新同事写一段自我介绍：

message = "I'm joining a new startup called Co1t today. Could you help me write a short introduction message to my teammates."

response = co.chat(
    model="command-a-plus-05-2026",
    messages=[{"role": "user", "content": message}],
)

print(response.message.content[0].text)

返回对象里包含多个字段，最常用的是 response.message.content[0].text，也就是模型生成的正文文本。示例输出大致是一段带占位符的自我介绍草稿，提示使用者把姓名、职位、兴趣爱好填进去，最后还附了一句鼓励语。

消息列表除了字典写法，SDK 也支持用类型化对象构造，例如 messages=[cohere.UserMessage(content=message)]，两种写法效果一致，按项目风格选一种即可。

第二步：用更具体的指令收窄输出

提示词决定了模型往哪个方向生成。指令越具体，结果越接近你要的形态。最直接的改进方式是在提示词里补上对长度、格式、语气的要求。

把上一步的提示词改成「一句话」版本：

message = "I'm joining a new startup called Co1t today. Could you help me write a one-sentence introduction message to my teammates."

response = co.chat(
    model="command-a-plus-05-2026",
    messages=[{"role": "user", "content": message}],
)

print(response.message.content[0].text)

这次输出被压缩成一句完整的自我介绍，仍然保留了姓名、职位等占位符。可以看到，仅仅增加「one-sentence」这个约束，输出形态就发生了明显变化。

提示词能写多长，取决于模型支持的最大上下文长度。以 Command A 为例，上下文上限是 256k tokens。这个数字会随模型版本变化，实际使用时以官网当前信息为准。

第三步：用少样本示例控制风格与格式

前面两步用的都是零样本提示（zero-shot），也就是只给指令、不给例子。当输出需要遵循特定风格或固定格式时，给几个示例往往比写一大段说明更有效，这就是少样本提示（few-shot）。

下面这个例子要把用户的求助描述转成工单标题，并且要求标题风格与示例保持一致：

user_input = "Why can't I access the server? Is it a permissions issue?"

message = f"""Write a ticket title for the following user request:

User request: Where are the usual storage places for project files?
Ticket title: Project File Storage Location

User request: Emails won't send. What could be the issue?
Ticket title: Email Sending Issues

User request: How can I set up a connection to the office printer?
Ticket title: Printer Connection Setup

User request: {user_input}
Ticket title:"""

response = co.chat(
    model="command-a-plus-05-2026",
    messages=[{"role": "user", "content": message}],
)

print(response.message.content[0].text)

输出为 Ticket title: "Server Access Permissions Issue"，长度和措辞都与示例对齐。少样本提示的要点是示例本身要足够一致：如果三个示例的标题长度、大小写风格各不相同，模型也会跟着摇摆。

第四步：用 temperature 控制随机性

同一个提示词多次调用，输出可能不同。控制这种随机程度最常用的参数是 temperature，取值范围是 0.0 到 1.0。值越低，输出越可预测；值越高，输出越有「创造性」。

先看 temperature=0 的情况，连续调用三次：

message = "I like learning about the industrial revolution and how it shapes the modern world. How I can introduce myself in five words or less."

for idx in range(3):
    response = co.chat(
        model="command-a-plus-05-2026",
        messages=[{"role": "user", "content": message}],
        temperature=0,
    )
    print(f"{idx + 1}: {response.message.content[0].text}\n")

三次输出完全一致，都是 "Revolution Enthusiast"。这说明在低温度下，模型的选择高度收敛。

把参数改成 temperature=1，同样的循环再跑一次，结果就分散开了：一次给出带解释的长句，一次是 "Revolution fan."，一次是 "IR enthusiast."。三种表达都符合「五个词以内」的约束，但风格差异明显。

选择哪个值取决于场景：需要稳定、可复现的输出（比如批量生成工单标题、抽取字段）时用低温度；需要多样化文案、创意命名时用高温度。除了 temperature，Chat 接口还提供其他生成参数，以及多个 Command 模型变体，它们在质量和延迟上各有侧重，可以按业务要求挑选。

第五步：用 response_format 生成结构化 JSON

纯文本适合直接展示给人看，但如果输出要交给下游程序处理，就需要结构化数据。给 Chat 接口加上 response_format 参数，可以让模型按指定的 JSON Schema 生成对象。

response_format 需要两个部分：type 固定为 json_object，schema 描述 JSON 对象的结构，包括 type、required 和 properties。每个属性可以声明类型，也可以用 enum 限定取值范围。

下面把用户求助转成一条 IT 工单：

user_input = "Why can't I access the server? Is it a permissions issue?"

message = f"""Create an IT ticket for the following user request.
Generate a JSON object.

{user_input}"""

response = co.chat(
    model="command-a-plus-05-2026",
    messages=[{"role": "user", "content": message}],
    response_format={
        "type": "json_object",
        "schema": {
            "type": "object",
            "required": ["title", "category", "status"],
            "properties": {
                "title": {"type": "string"},
                "category": {
                    "type": "string",
                    "enum": ["access", "software"],
                },
                "status": {
                    "type": "string",
                    "enum": ["open", "closed"],
                },
            },
        },
    },
)

json_object = json.loads(response.message.content[0].text)
print(json_object)

返回的文本可以直接被 json.loads 解析，得到类似 {'title': 'Unable to Access Server', 'category': 'access', 'status': 'open'} 的字典。其中 category 落在 access 与 software 两个枚举值之内，status 落在 open 与 closed 之内，下游代码可以放心按固定分支处理。

设计 schema 时有两点值得注意：一是 required 里列出的字段必须出现在输出中，把关键字段都放进去；二是能用 enum 限定的字段尽量限定，这比在提示词里用自然语言描述取值范围可靠得多。

第六步：改用流式响应

前面所有示例都是非流式的：接口等模型把整段文本生成完毕，才一次性返回响应对象。对于较长的输出，用户会盯着空白界面等待。Chat 接口支持流式模式，开启后每生成一个 token 就返回一次，可以边生成边展示。

流式调用的关键是在请求里打开流式开关，然后遍历返回的事件序列，把增量文本拼接起来。与非流式相比，代码结构从「一次拿到完整结果」变成「循环累积片段」，其余参数（模型、消息、temperature、response_format）的用法不变。

流式模式特别适合聊天界面、长文生成、实时摘要这类需要即时反馈的场景。如果输出很短，或者结果要整体交给下游程序解析，非流式反而更简单。

一个完整示例

把上面的能力串起来，做一个能处理新员工提问的入职助手：接收一条自由文本提问，输出结构化的处理结果，字段固定、可直接入库。

import cohere
import json

co = cohere.ClientV2(api_key="COHERE_API_KEY")

user_input = "I'm joining Co1t today. Could you help me write a one-sentence introduction message to my teammates?"

message = f"""You are an onboarding assistant for new hires.
Handle the following request and return a JSON object.

Request: {user_input}"""

response = co.chat(
    model="command-a-plus-05-2026",
    messages=[{"role": "user", "content": message}],
    temperature=0,
    response_format={
        "type": "json_object",
        "schema": {
            "type": "object",
            "required": ["category", "reply", "needs_followup"],
            "properties": {
                "category": {
                    "type": "string",
                    "enum": ["introduction", "it_support", "other"],
                },
                "reply": {"type": "string"},
                "needs_followup": {"type": "boolean"},
            },
        },
    },
)

result = json.loads(response.message.content[0].text)
print(result["category"])
print(result["reply"])
print(result["needs_followup"])

这个例子里，temperature=0 保证同一输入得到稳定结果，response_format 保证输出字段固定，category 的枚举值让后续路由逻辑可以直接写 if/elif。把 user_input 换成其他提问，比如服务器访问问题，category 会落到 it_support，reply 则给出对应的处理建议。

如果要把它做成真正的服务，可以在外层加一层循环读取用户输入，并把 reply 字段以流式方式推给前端；也可以把 needs_followup 为真的记录挑出来转人工处理。

注意事项

• 模型 ID 会更新：示例中使用的模型 ID 只是当前可用的一个版本，Command 系列会持续推出新模型。上线前请核对官网当前的模型列表与命名，不要假设某个 ID 永久有效。
• 上下文长度有上限：提示词长度受模型最大上下文限制，Command A 为 256k tokens。少样本示例堆得太多会挤占可用空间，示例数量要克制。
• temperature 的取值范围是 0.0 到 1.0：超出范围的行为没有保证，不要传入越界值。低温度不等于完全确定，只是收敛程度更高。
• 结构化输出仍需校验：即使指定了 schema，也建议在 json.loads 外层加异常处理，并对关键字段做类型检查，避免上游变更导致下游崩溃。
• API Key 不要外泄：示例中的 COHERE_API_KEY 是占位符，实际使用时从环境变量或密钥管理服务读取，不要写死在代码里。
• 价格、配额与可用模型以官网当前信息为准：不同模型的计费方式、速率限制和地区可用性可能调整，接入生产前请查阅官方页面确认。