Delphi 中的 Anthropic Claude——完整教程 (2026)

2026年5月28日 · 组件

为什么需要用于 Claude 的原生 Delphi 组件？

Anthropic Claude 是市场上能力最强的 AI 家族之一，但每个公开示例都使用 Python 或 Node。对于 Delphi 和 C++Builder 开发者，手工调用 REST 端点意味着手工编写 JSON、应对 Server-Sent Events、管理 TLS、处理速率限制，并在 Anthropic 每次发布新功能时重写样板代码——他们大约每季度都会发布新功能。sgcWebSockets 附带的 TsgcHTTP_API_Anthropic 组件消除了这种摩擦。它是围绕完整 Anthropic 界面（消息、流式传输、视觉、工具使用、扩展思考、提示缓存、文件、批处理以及 Model Context Protocol 连接器）的强类型包装器，您可以将它放在窗体上，并在任何 VCL、FMX 或控制台应用程序中使用它。

本教程通过可工作的 Delphi 代码演示每个主要功能。到结束时，您将能够构建聊天客户端、启用视觉的文档分析器、代理工具运行器和成本优化的生产管道。所有代码段都针对最新的 claude-sonnet-4-20250514 和 claude-opus-4-20250514 模型，并且所有代码段都在 Delphi 7 到 Delphi 13 上无修改地运行。

在我们深入之前，关于设计理念的简短说明。该组件有意公开两个界面。"快速"界面（_CreateMessage、_CreateMessageStream、_CreateMessageWithImage 等方法）接受几个字符串并返回一个字符串——非常适合原型、演示以及您不关心 temperature、top-p、metadata 或 stop sequences 的 80% 调用。"类型化"界面（TsgcAnthropicClass_Request_Messages 和 TsgcAnthropicClass_Response_Messages 等类）让您完全控制 Anthropic API 支持的每个参数，具有强类型和 IDE 自动完成。使用快速 API 学习；推广到类型化 API 用于生产。同一组件，两个层，没有重复。

1. 设置和您的第一条消息

将 sgcHTTP_API_Anthropic 添加到您的 uses 子句，创建组件，设置您的 API 密钥（从 console.anthropic.com 获取一个），然后调用 _CreateMessage。这是与 Claude 通信的绝对最小值。

uses
  sgcHTTP_API_Anthropic;

var
  oClaude: TsgcHTTP_API_Anthropic;
  vReply : string;
begin
  oClaude := TsgcHTTP_API_Anthropic.Create(nil);
  try
    oClaude.AnthropicOptions.ApiKey := 'sk-ant-api03-...';
    vReply := oClaude._CreateMessage(
      'claude-sonnet-4-20250514',
      'Write a haiku about Pascal compilers.');
    ShowMessage(vReply);
  finally
    oClaude.Free;
  end;
end;

该组件承担了繁重的工作：它构建 JSON 请求体、设置 x-api-key 和 anthropic-version 标头、向 /v1/messages 发布请求，并将响应解析为简单的 Delphi 字符串。如果您需要完全控制请求参数，请使用类型化的 TsgcAnthropicClass_Request_Messages 类。

一个操作提示：永远不要将 API 密钥嵌入二进制文件。从环境变量、注册表项或密钥管理器读取它。Anthropic 现在扫描 GitHub 以查找泄露的密钥并自动吊销它们——您不希望在周五下午 6 点发布更新，因为有人截取了您的 .pas 文件。

2. 使用 SSE 的流式响应

同步调用对于短提示来说很好，但对于聊天 UI，您希望 token 在 Claude 生成它们时出现。Anthropic 将响应作为 Server-Sent Events 流式传输，该组件通过 OnHTTPAPISSE 事件公开它们。

procedure TForm1.FormCreate(Sender: TObject);
begin
  oClaude := TsgcHTTP_API_Anthropic.Create(Self);
  oClaude.AnthropicOptions.ApiKey := 'sk-ant-api03-...';
  oClaude.OnHTTPAPISSE := ClaudeSSE;
end;

procedure TForm1.ClaudeSSE(Sender: TObject;
  const aEvent, aData: string; var Cancel: Boolean);
var
  vDelta: string;
begin
  // aEvent values: message_start, content_block_delta,
  //                content_block_stop, message_stop
  if aEvent = 'content_block_delta' then
  begin
    vDelta := oClaude.SSEExtractText(aData);
    Memo1.Text := Memo1.Text + vDelta;
    Application.ProcessMessages;
  end;
end;

procedure TForm1.btnAskClick(Sender: TObject);
begin
  Memo1.Clear;
  oClaude._CreateMessageStream(
    'claude-sonnet-4-20250514',
    edtPrompt.Text);
end;

一个值得注意的细节：流式传输在后台线程上运行，因此在生产代码中通过 TThread.Synchronize 或 TThread.Queue 更新 UI。上面的代码段为简洁起见使用 ProcessMessages。另一个：SSE 流按顺序发送多种事件类型（message_start、content_block_start、重复的 content_block_delta、content_block_stop、message_delta、message_stop），您应该忽略您不需要的那些。辅助方法 SSEExtractText 处理从 content_block_delta 中提取文本 delta 的常见情况；对于使用统计和停止原因，您直接解析 message_delta。

对于任何面向用户的聊天 UI，流式传输至关重要——用户认为在 400 毫秒内开始的响应很快，即使完整答案需要十秒钟。没有流式传输，他们盯着旋转器看十秒钟，并认为应用程序坏了。成本相同：流式和非流式请求的计费方式相同。

3. 视觉——发送图像

Claude 可以分析 JPEG、PNG、GIF 和 WebP 图像。您将它们作为公共 URL 或 base64 编码的字节传递。该组件为 URL 情况公开 _CreateMessageWithImage，为其他所有情况公开类型化 API。

var
  oRequest : TsgcAnthropicClass_Request_Messages;
  oMessage : TsgcAnthropicClass_Request_Message;
  oImage   : TsgcAnthropicClass_Request_Content_Image;
  oResponse: TsgcAnthropicClass_Response_Messages;
begin
  oRequest := TsgcAnthropicClass_Request_Messages.Create;
  try
    oRequest.Model     := 'claude-sonnet-4-20250514';
    oRequest.MaxTokens := 1024;

    oMessage := oRequest.NewMessage('user');
    oMessage.AddText('Describe what you see and read any text.');

    oImage := oMessage.AddImage;
    oImage.Source.LoadFromFile('C:\invoices\inv-2026-05-12.png');
    oImage.MediaType := 'image/png';

    oResponse := oClaude.CreateMessage(oRequest);
    try
      Memo1.Lines.Add(oResponse.Content[0].Text);
    finally
      oResponse.Free;
    end;
  finally
    oRequest.Free;
  end;
end;

视觉非常适合扫描发票上的 OCR、支持票据中的截图分类、图表解读，以及任何确定性 OCR 引擎在布局上会挣扎的任务。注意 token 成本：1024x1024 图像消耗大约 1,600 个输入 token。Anthropic 在处理之前将长边大于 1568px 的任何东西调整大小，因此上传 4K 截图毫无意义——在您一侧缩小并节省带宽。

过去一年中我们看到 Delphi 公司发布的实际用例：从对传统 OCR 管道来说太不一致的供应商 PDF 中提取行项目；在路由到专业软件之前将医学影像分类为大类别；从现场服务照片读取仪表值；在帮助台票据中分类 UI 错误截图（"截图显示布局问题还是数据问题？"）。在每种情况下，胜利不是原始准确性——而是消除了编写和维护脆弱的、每文档解析器的需要。

4. 工具使用（函数调用）

工具使用让 Claude 决定何时调用您的 Pascal 函数。您使用名称、描述和参数的 JSON Schema 声明每个工具。当 Claude 响应一个 tool_use 块而非纯文本时，您执行调用并将结果反馈到对话中。

var
  oRequest: TsgcAnthropicClass_Request_Messages;
  oTool   : TsgcAnthropicClass_Request_Tool;
begin
  oRequest := TsgcAnthropicClass_Request_Messages.Create;
  oRequest.Model     := 'claude-sonnet-4-20250514';
  oRequest.MaxTokens := 1024;

  oTool := oRequest.NewTool;
  oTool.Name        := 'get_stock_price';
  oTool.Description := 'Return the current bid/ask for a US ticker symbol.';
  oTool.InputSchema :=
    '{"type":"object",' +
     '"properties":{"symbol":{"type":"string","description":"Ticker, e.g. AAPL"}},' +
     '"required":["symbol"]}';

  oRequest.NewMessage('user').AddText('What is Apple trading at?');

  oResponse := oClaude.CreateMessage(oRequest);
  if oResponse.StopReason = 'tool_use' then
  begin
    vSymbol := oResponse.ToolUse[0].InputAsJSON.S['symbol'];
    vPrice  := MyQuoteFeed.Quote(vSymbol);        // your code
    oClaude.SendToolResult(oResponse.ToolUse[0].Id,
      Format('{"bid":%.2f,"ask":%.2f}', [vPrice.Bid, vPrice.Ask]));
  end;
end;

通过链接工具构建代理工作流：研究代理可能结合 web_search、read_pdf 和 send_email 工具。始终保持 iMaxIterations 守卫，以便行为不当的模型不能无限循环。在生产中，出于成本原因，我们将每个用户回合的工具调用上限设为 5；如果 Claude 需要更多，这通常表示提示或工具设计有问题。

工具调用质量的最大决定因素是描述文本。当描述精确时，模型大约 99% 的时间使用正确的参数选择正确的工具（"返回美国股票代码的当前 bid/ask。仅用于股票，不用于加密货币或外汇"）；当描述模糊时，它们降到约 70%（"获取价格"）。花时间。在描述中添加示例。说明工具不做什么。未来的您，在晚上 11 点调试 0.40 美元的幻觉函数调用时，会感谢现在的您。

5. 扩展思考

Claude 4 引入了思考模式，模型在回答之前逐步推理问题。您以 token 分配思考预算，Claude 返回与最终答案分开的推理跟踪。对于数学、代码审查和多步分析，这是一个游戏规则改变者。

oRequest.Thinking.Enabled       := True;
oRequest.Thinking.BudgetTokens  := 8000;   // soft cap on internal reasoning
oRequest.MaxTokens              := 16000;

oRequest.NewMessage('user').AddText(
  'A train leaves Madrid at 07:00 doing 220 km/h. Another leaves ' +
  'Barcelona at 07:15 doing 250 km/h. The route is 621 km. ' +
  'Where do they meet?');

oResponse := oClaude.CreateMessage(oRequest);
MemoThinking.Lines.Text := oResponse.Thinking;   // reasoning trace
MemoAnswer.Lines.Text   := oResponse.Content[0].Text;

谨慎使用扩展思考——推理 token 按输出计费，因此 Opus 4 上 16k token 的思考预算可能比普通调用成本更高。将其保留用于正确性比延迟更重要的问题。良好契合：法律文件分析、财务核对、复杂 SQL 生成、调试堆栈跟踪、多约束调度。不良契合：聊天回复、内容分类、简单查找——思考时间和成本不合理。

一个有用的技巧是在您的 UI 中将推理跟踪公开为可折叠的"显示思考"部分，就像公共 Claude 应用程序所做的那样。高级用户喜欢看到模型如何得出答案；普通用户忽略它。无论哪种方式，您都可以免费获得审计跟踪。

6. 提示缓存

如果您不断发送相同的长系统提示、知识库或工具定义，提示缓存可以将成本降低高达 90%，并将首 token 时间减少 80%。您将一个内容块标记为可缓存；Anthropic 在他们一侧存储它 5 分钟（或带扩展缓存的 1 小时），并仅按更便宜的缓存读取价格在后续调用中重新计费。

var
  oSystem: TsgcAnthropicClass_Request_System;
begin
  oSystem := oRequest.NewSystemBlock;
  oSystem.Text         := LoadFile('C:\kb\product-manual.txt'); // 50k tokens
  oSystem.CacheControl := 'ephemeral';        // mark as cacheable

  oRequest.NewMessage('user').AddText('How do I configure SSL on the server?');
  oResponse := oClaude.CreateMessage(oRequest);

  // Inspect cache stats
  ShowMessage(Format('Cache: created=%d, read=%d, input=%d, output=%d',
    [oResponse.Usage.CacheCreationInputTokens,
     oResponse.Usage.CacheReadInputTokens,
     oResponse.Usage.InputTokens,
     oResponse.Usage.OutputTokens]));
end;

经验法则：您在五分钟内重用的超过 1,024 个 token 的任何内容都值得缓存。大型文档语料库、few-shot 示例和大型工具模式是明显的候选者。会计：缓存写入比普通输入 token 成本高 25%，缓存读取成本是普通输入 token 的 10%。因此，您在第二次命中后收支平衡，并从第三次开始节省真正的钱。对于针对 40k token 知识库每分钟回答 50 个问题的客户支持机器人，提示缓存通常将每月 Anthropic 账单削减 80–85%。

您可以每个请求最多标记四个内容块为可缓存。常见模式是：工具（可缓存，很少更改）、系统提示（可缓存，很少更改）、大型文档（可缓存，每会话更改）、最近消息（不可缓存，每回合更改）。该组件自然处理这种分层——只需在您想要缓存的任何块上设置 CacheControl。

7. MCP 连接器

Model Context Protocol 让 Claude 与远程工具服务器通信，而无需您手工包装每个工具。将组件指向 MCP 服务器 URL，Claude 就可以发现工具、调用它们并链接结果。

oRequest.MCPServers.Add(
  'weather-mcp',
  'https://mcp.example.com/weather',
  'Bearer ' + GetMcpToken);

oRequest.NewMessage('user').AddText(
  'What is the weather like in Madrid and should I take an umbrella?');

oResponse := oClaude.CreateMessage(oRequest);
ShowMessage(oResponse.Content[0].Text);

将 MCP 连接器与您自己的 TsgcAI_MCP_Server（在单独的教程中介绍）结合起来，您将获得一个完全 Delphi 原生的代理，该代理将您的域 API 公开给任何支持 MCP 的 AI 客户端——Claude Desktop、Cursor、Continue、您自己的应用以及任何说该协议的东西。身份验证是您的责任：传递 bearer 令牌或签名标头，并在服务器端验证。Anthropic 看不到您的凭据——MCP 连接器握手将令牌从请求路由到目标服务器。

对于多租户 SaaS 部署，典型模式是每个租户一个 MCP 服务器，租户 ID 嵌入在 URL 或 bearer 令牌中。Claude 调用每个租户的工具，从不交叉污染数据。我们看到生产部署从单个对话扇出到 200 多个 MCP 服务器。

生产清单

在将 Anthropic 驱动的 Delphi 应用切换到生产之前，浏览这个简短列表：

关注点	如何处理
API 密钥存储	环境变量或 OS 密钥存储，从不硬编码
429 / 529 重试	带抖动的指数退避，最多 3 次尝试
成本上限	跟踪每请求的 `Usage`，超过每日预算后拒绝新调用
PII 编辑	在发送到 API 之前剥离电子邮件/SSN/CC 号码
模型版本固定	使用完整的日期模型名称；不要依赖"latest"别名
提示版本控制	将系统提示与代码一起存储在源代码控制中
遥测	记录每次调用的模型、输入 token、输出 token、延迟

接下来去哪

本教程涵盖了您 95% 的时间需要的八个功能。该组件还支持消息批处理（数千个提示的廉价异步处理——比同步调用便宜 50%，非常适合夜间扩充作业）、Files API（上传一次，永远引用——非常适合您反复查询的大型 PDF）、token 计数（在付款前估算成本）和结构化 JSON 输出（强制模式一致性，不再有解析错误）。浏览 Anthropic 组件页面以获取完整功能矩阵，如果您还没有安装 sgcWebSockets，请前往开始使用中心。

如果您在 Delphi 中用 Claude 构建了一些有趣的东西——代理、副驾驶、文档分析器——告诉我们。我们喜欢看到 Pascal 开发者在 AI 摩擦消失后所做的事情。