Chat-分销版与文心千帆对接指南：从入门到实战

一、技术对接前的核心准备

1.1 明确接入场景与需求

Chat-分销版作为对话式营销系统，接入文心千帆需优先确定核心场景：

• 智能客服：利用NLP能力处理高频咨询（如订单查询、退换货政策）
• 营销话术生成：基于用户画像动态生成促销文案
• 多轮对话管理：实现复杂业务场景的流程引导（如保险理赔）

关键指标：需预估QPS（每秒查询数）、响应延迟容忍度（建议≤800ms）、数据安全等级（如是否涉及PII信息）。

1.2 账号与权限配置

1. 注册文心千帆平台
   访问文心千帆官网，完成企业实名认证，获取API Key与Secret Key。

2. 服务开通
   在控制台开通「自然语言处理」-「文心一言API」服务，选择适合的套餐（免费版/付费版）。

3. IP白名单设置
   将Chat-分销版服务器IP添加至白名单，避免因安全策略拦截请求。

二、API调用技术实现

2.1 认证机制解析

文心千帆采用API Key + Secret Key双因子认证，需通过HMAC-SHA256算法生成签名：

import hmac
import hashlib
import base64
import time
def generate_signature(secret_key, method, path, timestamp, body=""):
    message = f"{method}\n{path}\n{timestamp}\n{body}"
    digest = hmac.new(
        secret_key.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).digest()
    return base64.b64encode(digest).decode('utf-8')
# 示例调用
timestamp = str(int(time.time()))
signature = generate_signature(
    secret_key="YOUR_SECRET_KEY",
    method="POST",
    path="/v1/chat/completions",
    timestamp=timestamp,
    body='{"messages":[{"role":"user","content":"你好"}]}'
)

2.2 核心API参数配置

参数	类型	说明	示例值
messages	List	对话历史，role需为user/assistant	[{"role":"user","content":"推荐一款手机"}]
model	String	模型版本（可选）	"ERNIE-3.5-Turbo"
temperature	Float	创造力参数（0.0~1.0）	0.7
max_tokens	Integer	响应最大长度	512

2.3 完整请求示例（Python）

import requests
import json
def call_wenxin_api(api_key, secret_key, prompt):
    url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions"
    headers = {
        "Content-Type": "application/json",
        "X-BD-API-KEY": api_key
    }
    timestamp = str(int(time.time()))
    signature = generate_signature(secret_key, "POST", "/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions", timestamp, json.dumps({"messages": [{"role": "user", "content": prompt}]}))
    headers["X-BD-SIGNATURE"] = signature
    headers["X-BD-TIMESTAMP"] = timestamp
    data = {
        "messages": [{"role": "user", "content": prompt}]
    }
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()
# 调用示例
result = call_wenxin_api(
    api_key="YOUR_API_KEY",
    secret_key="YOUR_SECRET_KEY",
    prompt="用专业术语解释量子计算"
)
print(json.dumps(result, indent=2))

三、高级功能集成

3.1 对话上下文管理

实现多轮对话需维护会话状态，建议采用Redis存储历史记录：

import redis
r = redis.Redis(host='localhost', port=6379, db=0)
def manage_conversation(session_id, user_input):
    # 获取历史对话
    history = json.loads(r.get(session_id) or "[]")
    history.append({"role": "user", "content": user_input})
    # 调用API
    response = call_wenxin_api(api_key, secret_key, user_input)
    assistant_reply = response["result"]
    history.append({"role": "assistant", "content": assistant_reply})
    # 存储更新后的对话
    r.setex(session_id, 3600, json.dumps(history))  # 1小时过期
    return assistant_reply

3.2 敏感词过滤

通过文心千帆的内容安全API实现前置审核：

def check_content_safety(text):
    safety_url = "https://aip.baidubce.com/rpc/2.0/solution/v1/text_censor/v2/user_defined"
    safety_data = {"text": text}
    safety_resp = requests.post(safety_url, headers=headers, data=json.dumps(safety_data))
    return safety_resp.json()["conclusionType"] == 1  # 1表示合规

四、性能优化与异常处理

4.1 并发控制策略

• 令牌桶算法限制QPS：
  ```python
  from collections import deque
  import time

class RateLimiter:
def init(self, qps):
self.tokens = qps
self.bucket = deque()

def acquire(self):
    now = time.time()
    while self.bucket and self.bucket[0] <= now - 1:
        self.bucket.popleft()
    if len(self.bucket) >= self.tokens:
        sleep_time = self.bucket[0] + 1 - now
        if sleep_time > 0:
            time.sleep(sleep_time)
        now = time.time()
    self.bucket.append(now)
    return True

#### 4.2 常见错误码处理
| 错误码 | 含义                  | 解决方案                     |
|--------|-----------------------|----------------------------|
| 401    | 认证失败              | 检查API Key/Secret Key有效性 |
| 429    | 请求频率过高          | 启用限流或升级套餐           |
| 500    | 服务器内部错误        | 实现重试机制（最多3次）      |
### 五、部署与监控
#### 5.1 日志收集方案
```python
import logging
logging.basicConfig(
    filename='wenxin_api.log',
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)
def log_api_call(prompt, response, latency):
    logging.info(f"Prompt: {prompt}\nResponse: {response}\nLatency: {latency}ms")

5.2 监控指标建议

• 成功率：API调用成功次数/总次数
• P99延迟：99%请求的响应时间
• Token消耗：按百万token计费需监控用量

六、安全合规要点

1. 数据脱敏：避免在prompt中传递手机号、身份证号等敏感信息
2. 审计日志：保留至少6个月的API调用记录
3. 合规声明：在用户协议中明确AI生成内容的责任边界

七、实战案例：电商客服机器人

场景：用户咨询”iPhone 15 Pro是否有现货”

实现步骤：

1. 用户输入触发意图识别（通过文心千帆的文本分类API）
2. 查询库存系统获取实时数据
3. 构造prompt：”用户问iPhone 15 Pro是否有现货，当前库存为[数量]台，请用友好语气回复”
4. 调用文心千帆生成回复：”亲，目前iPhone 15 Pro有[数量]台现货，支持24小时内发货哦~”

效果数据：

• 响应时间：平均650ms
• 解决问题率：82%
• 人力成本降低：60%

八、常见问题解答

Q1：免费版与付费版的区别？
A：免费版每日限制100次调用，付费版按实际用量计费（约0.002元/千token），支持更高QPS。

Q2：如何处理API超时？
A：建议设置3秒超时，超时后返回预设话术（如”客服繁忙，请稍后再试”），同时记录日志供后续分析。

Q3：是否支持私有化部署？
A：文心千帆当前仅提供SaaS服务，如需私有化部署可联系商务团队评估。

通过以上技术方案，Chat-分销版可高效接入文心千帆，实现对话能力的智能化升级。实际开发中需结合业务场景持续调优，建议先在小流量环境验证，再逐步扩大规模。