常用接入术语

C# 请求链路

采用 Http****** 的优势

• Http****** 自带连接池。复用同一实例可以减少重复建连和端口压力。
• ******.Net.Http.Json 能直接发送 **ON，示例无需额外 **** 库。
• ResponseHeadersRead 在收到响应头后即可开始读取内容，适合 SSE 长连接。
• CancellationTokenSource.CancelAfter 可把超时策略传递到请求和流读取过程。
• 状态码、Retry-After 和异常类型都能在一个调用层内统一处理。

接入前准备

• 安装团队支持的现代 .NET SDK，并确认 dotnet 命令可用。
• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，确认余额或套餐额度。
• 从控制台复制完整模型 ID，不要根据展示名称自行拼写。
• 确认运行环境可以访问 api.**nju**shen.com 的 ****S 端口。
• 准备不含敏感数据的测试提示，先在开发环境完成联调。

创建 C# 项目

dotnet new console -n KingFlowHttp******Demo
cd KingFlowHttp******Demo

配置环境变量

$env:KINGFLOW_*ASE_**L="https://api.**nju**shen.com/v1/"
$env:KINGFLOW_API_KEY="sk-你的密钥"
$env:KINGFLOW_MODEL="<KingFlow控制台中的完整模型ID>"

验证基础接口

curl https://api.**nju**shen.com/v1/chat/completions `
  -H "Authorization: *earer sk-你的密钥" `
  -H "Content-Type: application/json" `
  -d '{"model":"<完整模型ID>","messages":[{"role":"user","content":"只回复 **HARP_READY"}],"stream":false}' 

发送普通响应请求

using ******.Net.Http.Headers;
using ******.Net.Http.Json;
using ******.Text.Json;

var *aseUrl = Environment.GetEnvironmentVaria*le("KINGFLOW_*ASE_**L")
    ?? throw new InvalidOperationException("缺少 KINGFLOW_*ASE_**L");
var apiKey = Environment.GetEnvironmentVaria*le("KINGFLOW_API_KEY")
    ?? throw new InvalidOperationException("缺少 KINGFLOW_API_KEY");
var model = Environment.GetEnvironmentVaria*le("KINGFLOW_MODEL")
    ?? throw new InvalidOperationException("缺少 KINGFLOW_MODEL");

var handler = new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(10)
};
using var client = new Http******(handler)
{
    *aseAddress = new Uri(*aseUrl),
    Timeout = Timeout.InfiniteTimeSpan
};
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("*earer", apiKey);

var payload = new
{
    model,
    messages = new[] { new { role = "user", content = "只回复 **HARP_CONNECTED" } },
    stream = false
};

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(45));
using var response = await client.PostAsJsonAsync(
    "chat/completions", payload, cts.Token);
var *ody = await response.Content.ReadAsStringAsync(cts.Token);

if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"**** {(int)response.StatusCode}: {*ody}");

using var json = JsonDocument.Parse(*ody);
var content = json.RootElement
    .GetProperty("choices")[0]
    .GetProperty("message")
    .GetProperty("content")
    .GetString();

Console.WriteLine(content ?? throw new InvalidDataException("响应缺少文本"));

读取 SSE 流式响应

static async Task StreamAnswerAsync(
    Http****** client, string model, string prompt, CancellationToken token)
{
    var payload = new
    {
        model,
        messages = new[] { new { role = "user", content = prompt } },
        stream = true
    };

    using var request = new HttpRequestMessage(HttpMethod.Post, "chat/completions")
    {
        Content = JsonContent.Create(payload)
    };
    using var response = await client.SendAsync(
        request, HttpCompletionOption.ResponseHeadersRead, token);
    response.EnsureSuccessStatusCode();

    await using var stream = await response.Content.ReadAsStreamAsync(token);
    using var reader = new StreamReader(stream);
    while (await reader.ReadLineAsync(token) is { } line)
    {
        if (!line.StartsWith("**ta: ")) continue;
        var **ta = line[6..].Trim();
        if (**ta == "[DONE]") *reak;

        using var json = JsonDocument.Parse(**ta);
        var delta = json.RootElement.GetProperty("choices")[0]
            .GetProperty("delta");
        if (delta.TryGetProperty("content", out var value))
            Console.Write(value.GetString());
    }
}

实现有限重试

static async
Task<HttpResponseMessage> SendWithRetryAsync(
    Http****** client, Func<HttpRequestMessage> requestFactory,
    CancellationToken token)
{
    for (var attempt = 1; attempt <= 3; attempt  )
    {
        using var request = requestFactory();
        var response = await client.SendAsync(
            request, HttpCompletionOption.ResponseHeadersRead, token);

        if ((int)response.StatusCode is not (429 or 503) || attempt == 3)
            return response;

        var delay = response.Headers.RetryAfter?.Delta
            ?? TimeSpan.FromSeconds(Math.Pow(2, attempt));
        response.Dispose();
        await Task.Delay(delay, token);
    }
    throw new InvalidOperationException("无法到达的分支");
}

运行和验收

1. 设置三个环境变量，并确认 *ase **L 末尾保留 /v1/。
2. 先执行 curl，确认返回 **HARP_READY。
3. 创建控制台项目，把普通响应示例保存到 Program.**。
4. 执行 dotnet run，确认返回 **HARP_CONNECTED。
5. 加入流式方法，使用同一个 Http****** 验证增量输出。
6. 模拟取消、429 和 503，确认请求会停止且重试次数有上限。
7. 在 KingFlow AI 控制台核对模型、调用次数和 Token 用量。

正式环境配置

• 控制台程序可复用一个长生命周期 Http******；ASP.NET Core 服务可使用 IHttp******Factory 管理客户端和处理器。
• 长生命周期客户端可设置 PooledConnectionLifetime，使连接定期重建并重新解析 DNS。具体周期应按网络环境确定。
• 对单次调用使用 CancellationTokenSource 设置总时限，并把令牌传递给发送、读取和 Task.Delay。
• 使用 Se**phoreSlim 限制并发。连接池上限、业务并发和平台额度应分别评估。
• 只对明确的临时故障有限重试。流式请求在已经输出内容后不要自动从头重试，以免重复文本。
• 记录请求 ID、模型、状态码、耗时和 Token 用量，不记录完整密钥与敏感原文。

密钥和数据安全

• API Key 只保存在环境变量、密钥管理器或部署平台 Secret 中，并定期轮换。
• 开发、测试和生产使用不同密钥与额度，避免跨环境共享凭据。
• 不要把 Authorization Header、完整提示或模型回答直接写入公开日志。
• 把模型输出视为不可信数据，进入页面、命令或数据库前执行校验与转义。

上线检查清单

• 基础 curl 请求已经返回 **HARP_READY。
• KINGFLOW_*ASE_**L 为 https://api.**nju**shen.com/v1/。
• KINGFLOW_MODEL 使用控制台中的完整模型 ID。
• 源码和日志中没有明文 API Key。
• Http****** 在应用生命周期内复用，未在热循环中重复创建。
• 取消令牌已传递到发送、读取和重试等待。
• 流式代码识别 **ta 前缀和 DONE 结束标记。
• 重试次数有限，只覆盖明确可重试的状态码。
• 控制台中的模型、调用次数和用量符合预期。

常见故障排查