常见问题

认证相关

如何获取 API Key？

访问 Wolian AI 客户端管理
使用你的账户登录
点击”+ 创建”按钮创建新的客户端
确保密钥状态为”已激活”（绿色标识）
点击复制按钮，复制并安全保存 API Key

注意：密钥仅在创建时完整显示一次，请妥善保管。

API Key 泄露了怎么办？

如果怀疑 API Key 泄露，请立即： 1. 在 Wolian AI 平台中撤销该密钥 2. 创建新的 API Key 并激活 3. 更新所有使用旧 Key 的应用 4. 监控账户使用情况是否异常

为什么一直返回 401 错误？

常见原因：

API Key 格式错误（检查是否包含 Bearer 前缀）
API Key 已过期或被撤销
请求头中缺少 Authorization 字段
使用了错误的环境变量名

解决方法：

# 检查 API Key 格式
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://huajune.duliday.com/api/v1/models

模型与工具

如何查看我可以使用哪些模型？

调用 GET /api/v1/models 端点：

curl -X GET https://huajune.duliday.com/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY"

返回你账户可访问的所有模型列表。

为什么某个模型返回 403 错误？

可能原因：

该模型不在你的许可列表中
账户权限不足
模型 ID 拼写错误

解决方法：

使用 GET /api/v1/models 查看可用模型
联系销售团队申请权限
检查模型 ID 是否正确（区分大小写）

如何启用工具调用？

在请求中添加 allowedTools 数组，并提供必要的上下文：

启用工具示例

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [
    { "role": "user", "content": "候选人问：薪资待遇怎么样？" }
  ],
  "allowedTools": ["zhipin_reply_generator"],
  "context": {
    "preferredBrand": "蜀地源冒菜",
    "configData": { ... },
    "replyPrompts": { ... }
  }
}

查看可用工具：

查看工具列表

curl -X GET https://huajune.duliday.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"

工具需要哪些上下文？

每个工具的 requiredContext 不同：

zhipin_reply_generator: 需要 configData 和 replyPrompts ✅ 推荐用于业务场景
bash: 需要 sandboxId（E2B 沙盒环境）⚠️ 一般不推荐使用

推荐：使用 zhipin_reply_generator 等业务工具，它们更贴合实际的招聘场景，无需额外的沙盒环境配置。

使用 GET /api/v1/tools 查看每个工具的具体要求。

工具调用是如何工作的？

花卷智能体 API 采用服务端自动执行模式，一次请求即可完成所有工具调用。完整流程：

用户发送请求：包含 allowedTools 参数和必要的上下文
服务端自动处理：
- AI 决定需要调用工具
- 服务端自动执行工具
- AI 理解执行结果
- 生成最终回复
返回完整历史：响应包含所有中间步骤（tool-call 和 tool-result）

请求示例

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [
    { "role": "user", "content": "候选人问：薪资待遇怎么样？" }
  ],
  "allowedTools": ["zhipin_reply_generator"],
  "context": {
    "preferredBrand": "蜀地源冒菜",
    "configData": { ... },
    "replyPrompts": { ... }
  }
}

无需多轮请求：服务端自动完成所有工具调用，最多可执行 30 步。

详细说明请参阅：

如何查看工具执行的中间过程？

工具在服务端自动执行，有两种方式查看执行过程：方式 1：使用流式输出（实时监控）

流式监控

const response = await fetch(url, {
  body: JSON.stringify({
    stream: true,
    allowedTools: ["zhipin_reply_generator"],
    context: { ... },
    ...
  })
});

const reader = response.body.getReader();
// 监听 event: tool 事件，实时查看工具调用过程

方式 2：检查响应中的 messages 数组（非流式）

查看完整历史

const data = await response.json();

// 响应包含完整执行历史
data.data.messages.forEach(msg => {
  msg.parts.forEach(part => {
    if (part.type === 'dynamic-tool') {
      console.log('工具调用:', part.toolName);
      console.log('输入:', part.input);
      if (part.output) {
        console.log('输出:', part.output);
      }
    }
  });
});

详见工具调用 - 流式输出

功能使用

流式输出和非流式输出有什么区别？

特性	流式 (`stream: true`)	非流式 (`stream: false`)
响应方式	实时逐字返回	一次性返回完整内容
用户体验	打字机效果，感知更快	需要等待完整生成
适用场景	聊天界面、交互应用	后台处理、批量任务
Token 计费	相同	相同

推荐：面向用户的应用使用流式输出。

什么时候应该使用消息剪裁？

建议在以下情况启用消息剪裁：

对话轮次超过 20 轮
历史消息包含大量重复信息
需要优化成本
遇到上下文长度限制

不建议在以下情况使用：

短对话（< 10 轮）
需要完整历史信息的任务
关键业务对话

如何自定义系统提示词？

三种方式：方式 1：直接指定（推荐）

{
  "systemPrompt": "你是一个专业的Python导师"
}

✅ 最简单，直接覆盖 system prompt方式 2：使用 promptType + context.systemPrompts

{
  "promptType": "bossZhipinSystemPrompt",
  "context": {
    "systemPrompts": {
      "bossZhipinSystemPrompt": "你是BOSS直聘招聘助手..."
    }
  }
}

✅ promptType 同时决定工具集和 system prompt✅ 适合多场景管理方式 3：使用默认值 不设置任何参数，使用 "You are a helpful AI assistant."详见系统提示词文档

promptType 有什么作用？

promptType 有两个独立的作用：1. 决定工具集（内置、强制）

通过内置的 PROMPT_TOOL_MAPPING 自动启用对应工具
例如：bossZhipinSystemPrompt 自动启用招聘相关工具

2. 查找 system prompt（可选）

从 context.systemPrompts[promptType] 查找提示词文本
如果没有提供 context.systemPrompts，使用默认 system prompt

示例：

{
  "promptType": "bossZhipinSystemPrompt"
  // 效果：
  // ✅ 启用招聘工具集
  // ℹ️ 使用默认 system prompt（因为没有提供 context.systemPrompts）
}

查询可用的 promptType：

curl -X GET https://huajune.duliday.com/api/v1/prompt-types \
  -H "Authorization: Bearer YOUR_API_KEY"

性能与成本

如何降低 API 调用成本？

立即生效的方法：

启用消息剪裁（节省 40-70%）
使用成本更低的模型（如 Qwen Plus）
精简系统提示词
实现结果缓存

长期优化：

监控 Token 使用情况
批量处理请求
仅在必要时启用工具
定期审查和优化提示词

详见性能优化指南

为什么响应很慢？

可能原因：

输入消息太长（检查 Token 数量）
启用了多个复杂工具
网络延迟
服务端负载高

解决方法：

启用消息剪裁
减少不必要的工具
使用流式输出改善用户体验
检查网络连接

速率限制是多少？

默认限制：

每秒请求数 (RPS): 10
每分钟请求数 (RPM): 500
并发请求数: 5

超过限制会收到 429 Too Many Requests 错误。如需更高限额，请联系销售团队。

错误处理

收到 400 BadRequest 错误

常见原因：

请求参数格式错误
缺少必需的工具上下文
无效的 promptType

解决方法：

检查错误消息中的 details 字段
使用 validateOnly: true 预检查配置
查看 API 文档确认参数格式

收到 429 RateLimitExceeded 错误

说明超过了速率限制。解决方法：

// 实现指数退避重试
async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.statusCode === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}

如何追踪和报告问题？

每个响应都包含 correlationId：

const data = await response.json();
console.log('Correlation ID:', data.correlationId);

向技术支持报告问题时，请提供：

correlationId
请求时间
错误消息
请求参数（不要包含 API Key）

集成与开发

支持哪些编程语言？

花卷智能体 API 是标准的 REST API，支持所有能发送 HTTP 请求的编程语言：

JavaScript/TypeScript (Node.js, Browser)
Python
Java
Go
Ruby
PHP
C#/.NET
等等…

文档中提供了 JavaScript 和 Python 的详细示例。

如何在 React 中集成？

推荐使用流式输出：

function ChatBox() {
  const [messages, setMessages] = useState([]);

  const sendMessage = async (text) => {
    const response = await fetch('https://huajune.duliday.com/api/v1/chat', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: 'anthropic/claude-3-7-sonnet-20250219',
        messages: [...messages, { role: 'user', content: text }],
        stream: true
      })
    });

    const reader = response.body.getReader();
    // 处理流式响应...
  };

  return <div>{/* UI 组件 */}</div>;
}

详见流式输出功能

如何处理长时间运行的请求？

建议：

使用流式输出，可以实时看到进度
设置合理的超时时间（建议 60-120 秒）
实现重试机制
向用户显示加载状态

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 120000); // 120秒

try {
  const response = await fetch(url, {
    signal: controller.abort,
    ...options
  });
} finally {
  clearTimeout(timeoutId);
}

还有问题？

查看 API 文档

完整的 API 端点参考文档

联系技术支持

发送邮件获取人工支持

调试指南

学习调试技巧和工具

性能优化

优化 API 调用性能和成本

快速开始

核心概念

功能指南

最佳实践

认证相关

模型与工具

功能使用

性能与成本

错误处理

集成与开发

还有问题？

查看 API 文档

联系技术支持

调试指南

性能优化

​认证相关

​模型与工具

​功能使用

​性能与成本

​错误处理

​集成与开发

​还有问题？

查看 API 文档

联系技术支持

调试指南

性能优化

认证相关

模型与工具

功能使用

性能与成本

错误处理

集成与开发

还有问题？