一、引言
随着大模型在各类业务场景中落地，如何精准控制模型的输出风格、格式与内容，成为开发者的必修课。本文围绕 Claude API 的可调参数、进阶定制化选项，以及实战级提示工程技巧，给出详细示例与最佳实践，帮助你快速上手并打造高质量应用。
二、API 必选参数详解
在调用 Claude 的 /v1/chat/completions 接口时，三大必选参数如下。示例中使用 Python SDK（anthropic 包）：
pip install anthropic
from anthropic import Anthropic
client = Anthropic(api_key="YOUR_API_KEY")
response = client.completions.create(
model="claude-3-sonnet-20240229",
max_tokens=1024,
system="You are a polite assistant that always responds in Chinese.",
messages=[
{"role": "user", "content": "给我推荐三本科幻小说。"}
],
)
print(response.completion)
- model：选择合适算力与表现的模型版本（如
claude-3.5、claude-instant）。 - max_tokens：限制生成长度，避免过长或爆 token。
- messages：按顺序传入
user→assistant→user…，为对话提供上下文。
三、可选采样参数（控制随机性与创造力）
| 参数 | 含义 | 适用场景 |
|---|---|---|
temperature | 调整概率分布平滑度，0.0–1.0；数值越低越保守，越高越创新 | 创意写作（高），专业回答（低） |
top_k | 取概率最高的前 K 个标记，再从中随机选取下一个 token | 需要截断极低概率输出时 |
top_p | 累积概率至 P（0.0–1.0）为止，选中这部分 token 集合，再随机选 | 兼顾保守与创新，更多细微控制 |
注意：
temperature与top_k/top_p二者互斥，仅需配置其中一种采样策略。
3.1 调节 temperature 示例
from anthropic import Anthropic
client = Anthropic(api_key="YOUR_API_KEY")
response = client.completions.create(
model="claude-3-sonnet-20240229",
max_tokens=200,
temperature=0.3,
messages=[
{"role": "user", "content": "给我推荐五条东京三日游路线。"}
],
)
print(response.completion)
- 将
temperature调低至 0.3，可让回答更加聚焦于最优选项，减少偏离主题的创意输出。
3.2 调节 top_p 示例
from anthropic import Anthropic
client = Anthropic(api_key="YOUR_API_KEY")
response = client.completions.create(
model="claude-3-sonnet-20240229",
max_tokens=150,
top_p=0.9,
messages=[
{"role": "user", "content": "请给我三部近年最佳科幻电影推荐。"}
],
)
print(response.completion)
top_p=0.9表示候选集中累积概率达到 90% 的标记，既保留多样性，又防止极端低概率项。
四、进阶定制化参数
4.1 system prompt（系统提示）
在 create 的时候使用参数system，可提供全局策略或语气指令：
client.completions.create(
model="claude-3-sonnet-20240229",
max_tokens=150,
top_p=0.9,
system="You are Sherlock Holmes, assist me in solving mysteries.",#system提示词
messages=[ {"role": "user", "content": "请给我三部近年最佳科幻电影推荐。"} ],
)
- 应用场景：角色扮演、定制化人格、上下文注入。
4.2 stop_sequence（停止序列）
通过设置 stop_sequences，当模型输出遇到指定字符串时，立即截断：
response = client.completions.create(
model="claude-3-sonnet-20240229",
max_tokens=300,
system="使用xml格式的来格式化内容，<JSON_END>做为开始的标记，使用</JSON_END>作为结束的标记",
stop_sequences=["</JSON_END>"],
messages=[ ... ],
)
- 用途示例1：强制 JSON 输出
在 JSON 末尾加上
"</JSON_END>"，并将其添加到stop_sequences，避免多余自然语言。 - 用途示例2：敏感信息保护 当模型可能意外输出如信用卡号、IP 等敏感字段，可设定关键前缀或后缀为停止符，降低泄露风险。
五、提示工程（Prompt Engineering）实战技巧
5.1 长文档上下文注入
-
数据置顶：将长文本或文档内容放在 prompt 最前面，再追加指令，保证模型优先消化数据。
-
示例：
doc = "<DOCUMENT>\n" + open("manual.txt").read() + "\n</DOCUMENT>" query = "<QUERY>\n根据上文内容，帮我生成一份产品卖点总结，要求 5 条。\n</QUERY>" response = client.completions.create( model="claude-3-sonnet-20240229", max_tokens=500, messages=[ {"role": "user", "content": doc + "\n" + query}, ], ) print(response.completion)
5.2 自定义标签（类似 XML/HTML）
-
使用
<INSTRUCTION>、<DATA>、<OUTPUT_FORMAT>等标签，明确分段结构，增强模型对格式的遵循度。 -
示例：
prompt = """ <INSTRUCTION> 你是资深市场分析师，请根据以下数据生成周报。 </INSTRUCTION> <DATA> {"sales": 120000, "growth": "15%", "region": "华东区"} </DATA> <OUTPUT_FORMAT> - 第一部分：要点概述 - 第二部分：详细分析 </OUTPUT_FORMAT> """ response = client.completions.create( model="claude-3-sonnet-20240229", max_tokens=400, messages=[{"role": "user", "content": prompt}], ) print(response.completion)
5.3 引用与溯源
-
要求模型在答案中标注引用编号，并在末尾给出原文出处位置，提升“可验证性”。
-
示例：
prompt = """ <DOCUMENT> 【在此粘贴用户调研报告全文】 </DOCUMENT> <QUERY> 根据上文，请列出 3 条用户主要痛点，并在每条后以 [引用编号] 标注出处。 </QUERY> """ response = client.completions.create( model="claude-3-sonnet-20240229", max_tokens=300, messages=[ {"role": "user", "content": prompt}, ], ) print(response.completion)
5.4 Chain-of-Thought（思维链）
-
对于复杂推理或多步骤任务，可在 prompt 中加入：
“请先列出推理步骤，再给出最终结论：” -
注意：会明显增加生成长度与响应时间，仅在确实需要多步推理时启用。
六、综合示例：生成带引用的分析报告
from anthropic import Anthropic
client = Anthropic(api_key="YOUR_API_KEY")
document = open("customer_research.txt", encoding="utf-8").read()
user_prompt = f"""
<DOCUMENT>
{document}
</DOCUMENT>
<QUERY>
请基于以上文档，生成一份购买动机分析报告：
1. 按编号列出 3 个主要购买动机
2. 每条后面以 [引用编号] 标注出处
</QUERY>
"""
response = client.completions.create(
model="claude-3-sonnet-20240229",
max_tokens=800,
temperature=0.2,
stop_sequences=["</REPORT>"],
messages=[
{"role": "user", "content": user_prompt},
],
)
print(response.completion)
（示例输出）
1. 价格敏感型：[1] 80% 受访者最关注价格因素
2. 功能导向型：[3] “需要高性能处理”出现在第 4 段
3. 品牌忠诚型：[5] “品牌影响力强”在第 7 段
[1] 文档第 2 段 “80% 受访者关注价格”
[3] 文档第 4 段 “…对功能要求高…”
[5] 文档第 7 段 “品牌影响力显著”
</REPORT>
七、最佳实践与常见误区
- 参数互斥：
temperature与top_p/top_k不要同时配置，避免逻辑冲突。 - 标签格式：标签越清晰、层级越浅，模型遵从度越高。
- 示例优先级：若需要模型参考示例格式，可在 prompt 中提供 1–2 个“示例输出”，效果更稳定。
- 费用与性能：使用低温度（或小
max_tokens）可节省 API 费用、加快响应速度；高温度/大max_tokens则适合创意与深度生成。
