把百川Baichuan API接入业务系统时，最常遇到的疑问是：搜索增强和知识库问答到底怎么在同一个对话接口里生效？二者共享Chat Completions入口，却依赖不同参数组合。下文会从密钥准备开始，逐步完成可运行的Python调用示例。
一、环境准备与API Key获取
使用百川Baichuan API之前，需要先完成平台侧配置。打开百川智能开放平台，注册并登录账号后，进入控制台创建一个新的API应用。创建应用时可以填写应用名称、用途说明，平台通常允许为不同业务线建立多个应用，便于后续分别监控调用量和费用。创建完成后，在应用详情页找到API Key。这个密钥是调用接口的唯一凭证，必须妥善保管，不要提交到公开仓库。
为了后续代码不硬编码密钥，建议把API Key写入环境变量。Linux或macOS下可以在终端执行export命令，Windows下可以使用set命令或系统环境变量设置界面。生产环境中更推荐通过密钥管理服务或容器编排的Secret机制注入。百川API兼容OpenAI风格的请求格式，基础请求头需要携带Authorization和Content-Type两个字段，其中Authorization值为Bearer加上空格和API Key。
下面是一个最基础的curl调用示例，用于验证密钥是否可用。如果返回了正常的choices结构，说明网络和鉴权配置正确，可以继续深入搜索增强与知识库功能。
export BAICHUAN_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"
curl https://api.baichuan-ai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $BAICHUAN_API_KEY" \
-d '{
"model": "Baichuan3-Turbo",
"messages": [{"role": "user", "content": "你好，请简单介绍你自己"}],
"stream": false
}'
实际开发中建议使用Python的requests库统一处理请求。先在项目目录创建虚拟环境并安装requests，然后把密钥放在环境变量中读取。这样代码可以在不同机器上运行，不会因为密钥泄露带来安全风险。请求地址建议配置成常量，方便后续切换网络区域或代理。
二、开启搜索增强：让模型获取实时信息
普通大模型对话只依赖预训练时的参数知识，对于实时新闻、股价、天气、政策变更等问题无法给出准确答案。百川Baichuan API的搜索增强能力通过在请求体中加入search_enhance参数，让模型在生成回答前主动发起一次或多次联网搜索，并把搜索结果作为上下文拼接到推理过程中。这个参数通常是一个布尔值，设置为true即可开启。
开启搜索增强后，模型返回的内容会包含搜索结果引用。调用方式与普通对话完全一致，只是响应中会额外出现search_results字段。该字段是一个数组，每条结果包含标题、链接和摘要信息。你可以把这些引用展示给最终用户，方便用户确认信息来源。下面是一段完整的Python请求代码，演示如何携带该参数。
import requests
import json
url = "https://api.baichuan-ai.com/v1/chat/completions"
api_key = "sk-xxxxxxxx"
headers = {
"Authorization": "Bearer " + api_key,
"Content-Type": "application/json"
}
payload = {
"model": "Baichuan3-Turbo",
"messages": [
{"role": "system", "content": "你是一个信息检索助手，回答时请注明信息来源"},
{"role": "user", "content": "近期诺贝尔物理学奖授予了谁？"}
],
"search_enhance": True,
"stream": False
}
resp = requests.post(url, headers=headers, json=payload)
print(json.dumps(resp.json(), ensure_ascii=False, indent=2))
响应结构中除了常规的choices数组，还会包含搜索增强相关的元数据。下面是一个精简后的响应示例，展示了搜索结果的返回形式。需要注意不同模型版本字段名称可能略有差异，接入前最好以官方文档为准。
{
"id": "chatcmpl-xxxx",
"object": "chat.completion",
"created": 1710000000,
"model": "Baichuan3-Turbo",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "根据最新搜索结果显示，诺贝尔物理学奖授予了..."
},
"search_enhance": true,
"search_results": [
{
"title": "诺贝尔物理学奖揭晓",
"url": "https://www.ipipp.com/news/123",
"content": "瑞典皇家科学院宣布..."
}
]
}
]
}
搜索增强并非万能的。它适合需要实时信息或事实校验的场景，但会增加响应延迟和调用成本，因为模型需要额外等待搜索请求返回。对于企业内部私有数据，联网搜索无法触达，这时就需要知识库问答来补足。此外，如果用户问题本身与实时信息无关，开启搜索增强反而可能引入噪声，建议根据业务类型动态控制该参数。
三、知识库问答：注入自有文档
知识库问答的目标是让模型基于企业自有文档回答问题，而不是完全依赖公网信息。百川Baichuan API允许先创建知识库，再把PDF、Word、TXT等格式的文档上传到知识库中。上传成功后，调用对话接口时通过knowledge_ids参数指定要检索的知识库列表。模型会先根据用户问题在指定知识库中召回相关片段，再基于这些片段生成答案。
创建知识库和上传文档的步骤比较独立。可以先在控制台手动操作，也可以通过API自动化完成。下面代码演示了如何用Python创建一个名为产品帮助中心的知识库，并向其中上传一个本地PDF文件。上传接口返回的文档ID可以用于后续的文档管理，例如删除、重新解析或查看切分状态。
import requests
api_key = "sk-xxxxxxxx"
headers = {"Authorization": "Bearer " + api_key}
# 创建知识库
kb_resp = requests.post(
"https://api.baichuan-ai.com/v1/knowledge_base",
headers=headers,
json={"name": "产品帮助中心", "description": "客服问答知识库"}
)
knowledge_base_id = kb_resp.json()["id"]
# 上传文档
with open("help_center.pdf", "rb") as f:
upload_resp = requests.post(
"https://api.baichuan-ai.com/v1/knowledge_base/" + knowledge_base_id + "/documents",
headers=headers,
files={"file": f}
)
print(upload_resp.json())
上传完成后，文档会进入解析和切分阶段。大模型问答系统通常不会把整篇文档直接塞给模型，而是先把文档切成若干小片段，再根据用户问题与片段之间的相似度进行召回。因此文档切分粒度会直接影响问答质量。对于表格密集型文档，建议保留一定的结构信息；对于FAQ类文档，可以按问答对切分。部分平台还支持自定义切分规则，如果默认效果不佳，需要根据实际业务调整。
调用知识库问答接口时，只需要在原有请求中加入knowledge_ids字段。该字段是一个数组，可以同时指定多个知识库做联合检索。如果同时开启search_enhance和知识库检索，部分模型会优先使用知识库召回内容，不足时再触发联网搜索。下面是一个完整的调用示例。
import requests
import json
url = "https://api.baichuan-ai.com/v1/chat/completions"
api_key = "sk-xxxxxxxx"
headers = {
"Authorization": "Bearer " + api_key,
"Content-Type": "application/json"
}
payload = {
"model": "Baichuan3-Turbo",
"messages": [
{"role": "user", "content": "如何申请退款？"}
],
"knowledge_ids": [knowledge_base_id],
"search_enhance": False,
"stream": False
}
resp = requests.post(url, headers=headers, json=payload)
print(json.dumps(resp.json(), ensure_ascii=False, indent=2))
知识库问答的优势在于答案可溯源、内容可控，适合客服、内部办公、产品手册等场景。但它也要求文档质量足够高，且需要持续更新。如果文档过期，模型给出的答案也会跟着出错。因此建议建立文档更新流水线，在业务系统变更时自动同步到知识库，避免人工忘记上传导致回答滞后。
四、流式输出与错误处理
在交互式对话场景中，等待完整响应往往会让用户觉得卡顿。百川Baichuan API支持流式输出，通过把stream参数设为true，服务端会以SSE格式逐步返回生成内容。客户端可以一边接收一边渲染，提升用户体验。流式输出时响应体是分行的文本，每一行以data:开头，遇到[DONE]表示生成结束。
下面代码展示了如何使用requests的iter_lines逐行读取流式响应。需要注意的是，流式请求必须把stream参数同时设置为true，并且请求对象本身也要开启流式传输，否则客户端会等待完整响应后才开始解析。
import requests
import json
url = "https://api.baichuan-ai.com/v1/chat/completions"
api_key = "sk-xxxxxxxx"
headers = {
"Authorization": "Bearer " + api_key,
"Content-Type": "application/json"
}
payload = {
"model": "Baichuan3-Turbo",
"messages": [{"role": "user", "content": "总结一下搜索增强接口的注意事项"}],
"stream": True
}
resp = requests.post(url, headers=headers, json=payload, stream=True)
for line in resp.iter_lines():
if line:
decoded = line.decode("utf-8")
if decoded.startswith("data:"):
data = decoded[5:].strip()
if data and data != "[DONE]":
chunk = json.loads(data)
delta = chunk["choices"][0]["delta"].get("content", "")
print(delta, end="", flush=True)
实际开发中还要处理三类常见错误。第一类是401鉴权失败，通常是API Key错误或已过期；第二类是429限流，需要降低并发或实现指数退避重试；第三类是400参数错误，需要检查字段名是否拼写正确、类型是否匹配。建议在封装请求函数时统一捕获requests.exceptions.RequestException和JSON解析异常，避免单个请求失败拖垮整个任务。
另外，搜索增强和知识库检索都会引入额外的延迟。对于高并发业务，可以考虑设置合理的超时时间，并对非核心请求启用异步任务模式。例如用户提交问题后先返回任务ID，后台完成检索和生成后再通知结果。这种方案虽然复杂度更高，但能有效避免连接被长任务占满。
五、总结
百川Baichuan API把搜索增强和知识库问答统一到了对话接口中，调用门槛不高，关键在于理解不同参数的作用边界。搜索增强解决实时性问题，知识库问答解决私有数据问题，两者可以单独使用，也可以组合使用。集成时要重点关注密钥安全、文档切分策略、流式输出和错误重试机制。
如果业务对回答质量有更高要求，还可以在系统提示词中约束模型的回答风格，例如要求先给结论再给依据。对于搜索增强场景，建议把返回的搜索结果链接一并展示给用户；对于知识库问答场景，可以要求模型在回答末尾标注命中的文档名称。通过这些小调整，往往能显著提升最终答案的可用性。