当前位置：首页 > news >正文

.NET Core微服务调用SmallThinker-3B-Preview模型实战

news 2026/5/12 1:25:03

.NET Core微服务调用SmallThinker-3B-Preview模型实战

最近在折腾AI应用集成，发现很多团队都在探索如何把大模型能力嵌入到自己的业务系统里。如果你用的是.NET技术栈，可能会想：怎么才能优雅、稳定地把一个像SmallThinker-3B-Preview这样的模型服务，包装成自己微服务架构里的一环呢？

直接裸调HTTP接口当然可以，但在生产环境里，这远远不够。服务发现、连接管理、错误处理、性能监控，这些才是真正头疼的地方。今天，我就结合一个实际的场景，带你走一遍在.NET Core里构建一个健壮的模型调用微服务的完整过程。我们会从零开始，创建一个Web API，然后一步步加入生产级必备的“装备”，比如用HttpClientFactory管理连接、用Polly做熔断保护，最后打包成Docker镜像。整个过程，就像给一个核心能力套上一件坚固可靠的外衣。

1. 项目初始化与环境搭建

万事开头难，但第一步往往最简单。我们先来把项目架子搭起来。

1.1 创建项目与基础结构

打开你的命令行工具，或者直接在Visual Studio里操作。这里我们用.NET CLI来创建项目，这样更通用一些。

dotnet new webapi -n ModelInvoker.Microservice cd ModelInvoker.Microservice

这个命令会创建一个标准的ASP.NET Core Web API项目模板。接下来，我们需要引入几个核心的NuGet包，它们是我们构建健壮服务的基础。

dotnet add package Microsoft.Extensions.Http dotnet add package Polly.Extensions.Http dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

简单解释一下这几个包是干什么的：

Microsoft.Extensions.Http：提供了IHttpClientFactory，这是现代.NET中管理HTTP客户端生命周期的推荐方式，能有效避免套接字耗尽等问题。
Polly.Extensions.Http：为HTTP调用提供了一套完善的弹性策略库，比如重试、熔断、超时，后面我们会用它来保护对模型服务的调用。
Microsoft.Extensions.Diagnostics.HealthChecks：健康检查库，让我们的服务能对外报告自己的状态，这对于容器编排和负载均衡器至关重要。

1.2 配置模型服务连接信息

我们不应该把像模型服务地址、API密钥这样的敏感信息硬编码在代码里。.NET Core的配置系统非常好用，我们把它用起来。

首先，在appsettings.json文件里，添加一个配置节来存放模型服务的相关信息：

{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "ModelService": { "BaseUrl": "http://your-model-service-host:port/v1", // 替换为你的模型服务地址 "ApiKey": "your-api-key-here", // 替换为你的API密钥 "TimeoutSeconds": 30, "MaxRetryAttempts": 3 }, "AllowedHosts": "*" }

然后，我们创建一个对应的配置类ModelServiceOptions，这样就能以强类型的方式访问这些配置了。在项目里新建一个Options文件夹，并添加这个类：

namespace ModelInvoker.Microservice.Options; public class ModelServiceOptions { public const string ModelService = "ModelService"; public string BaseUrl { get; set; } = string.Empty; public string ApiKey { get; set; } = string.Empty; public int TimeoutSeconds { get; set; } = 30; public int MaxRetryAttempts { get; set; } = 3; }

2. 核心服务层实现

架子搭好了，接下来就该打造服务的核心——一个专门负责与SmallThinker-3B-Preview模型对话的“客户端”了。

2.1 定义模型交互的数据契约

在调用模型之前，我们需要定义请求和响应长什么样。通常，模型服务会接受一个包含prompt（提示词）的请求，返回生成的文本。我们创建两个类来表示它们。

在Models文件夹下，创建ModelRequest.cs和ModelResponse.cs：

namespace ModelInvoker.Microservice.Models; // 发送给模型服务的请求 public class ModelRequest { public string Prompt { get; set; } = string.Empty; // 可以根据SmallThinker-3B-Preview的API文档，添加其他参数，如max_tokens, temperature等 public int MaxTokens { get; set; } = 500; public double Temperature { get; set; } = 0.7; } // 从模型服务接收的响应 public class ModelResponse { public string GeneratedText { get; set; } = string.Empty; public long InferenceTimeMs { get; set; } // 可以包含其他元数据，如token使用量等 }

2.2 实现健壮的模型调用服务

这是最关键的一步。我们将创建一个服务类ModelInvokerService，它利用HttpClient来调用远程模型API，并集成Polly策略来处理各种故障。

在Services文件夹下，创建IModelInvokerService接口和它的实现：

using ModelInvoker.Microservice.Models; using ModelInvoker.Microservice.Options; using Microsoft.Extensions.Options; using System.Net.Http.Headers; using System.Text; using System.Text.Json; namespace ModelInvoker.Microservice.Services; public interface IModelInvokerService { Task<ModelResponse> GenerateTextAsync(ModelRequest request, CancellationToken cancellationToken = default); } public class ModelInvokerService : IModelInvokerService { private readonly HttpClient _httpClient; private readonly ModelServiceOptions _options; private readonly ILogger<ModelInvokerService> _logger; public ModelInvokerService(HttpClient httpClient, IOptions<ModelServiceOptions> options, ILogger<ModelInvokerService> logger) { _httpClient = httpClient; _options = options.Value; _logger = logger; // 配置HttpClient的基础地址和默认请求头（如认证） _httpClient.BaseAddress = new Uri(_options.BaseUrl); _httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", _options.ApiKey); _httpClient.Timeout = TimeSpan.FromSeconds(_options.TimeoutSeconds); } public async Task<ModelResponse> GenerateTextAsync(ModelRequest request, CancellationToken cancellationToken = default) { _logger.LogInformation("Sending request to model service for prompt: {PromptPrefix}...", request.Prompt[..Math.Min(50, request.Prompt.Length)]); var jsonContent = JsonSerializer.Serialize(request); using var httpContent = new StringContent(jsonContent, Encoding.UTF8, "application/json"); try { // 这里发送HTTP POST请求。实际端点（如/completions）需根据SmallThinker-3B-Preview的API文档确定 var response = await _httpClient.PostAsync("completions", httpContent, cancellationToken); response.EnsureSuccessStatusCode(); // 确保响应是成功的 var responseJson = await response.Content.ReadAsStringAsync(cancellationToken); var modelResponse = JsonSerializer.Deserialize<ModelResponse>(responseJson); if (modelResponse == null) { throw new InvalidOperationException("Failed to deserialize response from model service."); } _logger.LogInformation("Successfully received response from model service."); return modelResponse; } catch (HttpRequestException ex) { _logger.LogError(ex, "HTTP request failed when calling model service."); throw; // 向上抛出，由Polly策略或控制器处理 } catch (TaskCanceledException) when (!cancellationToken.IsCancellationRequested) { // 这通常是超时引起的 _logger.LogError("Request to model service timed out after {Timeout}s.", _options.TimeoutSeconds); throw new TimeoutException($"Model service request timed out after {_options.TimeoutSeconds} seconds."); } catch (Exception ex) { _logger.LogError(ex, "An unexpected error occurred while calling model service."); throw; } } }

注意看，我们在构造函数里配置了HttpClient，并且GenerateTextAsync方法里包含了基本的错误处理和日志记录。但这还不够弹性，我们马上用Polly来增强它。

3. 集成弹性与可观测性

一个直接对外部服务进行HTTP调用的微服务，必须考虑外部服务不稳定带来的影响。同时，我们也需要让外部知道自己的健康状况。

3.1 使用Polly实现熔断与重试

Polly的策略可以定义在依赖注入容器配置的地方。我们打开Program.cs文件（或Startup.cs，取决于你的.NET版本），添加以下代码来配置一个具名的、受保护的HttpClient。

using ModelInvoker.Microservice.Options; using ModelInvoker.Microservice.Services; using Polly; using Polly.Extensions.Http; var builder = WebApplication.CreateBuilder(args); // 1. 配置ModelServiceOptions builder.Services.Configure<ModelServiceOptions>( builder.Configuration.GetSection(ModelServiceOptions.ModelService)); // 2. 配置具有弹性策略的HttpClient builder.Services.AddHttpClient<IModelInvokerService, ModelInvokerService>() .AddPolicyHandler(GetRetryPolicy()) // 添加重试策略 .AddPolicyHandler(GetCircuitBreakerPolicy()); // 添加熔断器策略 // 定义重试策略：对于特定的HTTP状态码或异常，进行有限次数的重试。 static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy() { return HttpPolicyExtensions .HandleTransientHttpError() // 处理5xx、408（请求超时）、429（太多请求） .OrResult(msg => msg.StatusCode == System.Net.HttpStatusCode.TooManyRequests) // 明确处理429 .WaitAndRetryAsync( retryCount: 3, // 从配置读取 sleepDurationProvider: retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)), // 指数退避 onRetry: (outcome, timespan, retryAttempt, context) => { var logger = context.GetLogger(); logger?.LogWarning("Delaying for {delay}ms, then making retry {retry}.", timespan.TotalMilliseconds, retryAttempt); }); } // 定义熔断器策略：当故障达到一定阈值时，快速失败，避免雪崩。 static IAsyncPolicy<HttpResponseMessage> GetCircuitBreakerPolicy() { return HttpPolicyExtensions .HandleTransientHttpError() .CircuitBreakerAsync( handledEventsAllowedBeforeBreaking: 5, // 连续5次故障后熔断 durationOfBreak: TimeSpan.FromSeconds(30), // 熔断30秒 onBreak: (outcome, breakDelay) => { // 记录熔断开启 }, onReset: () => { // 记录熔断关闭 }, onHalfOpen: () => { // 记录半开状态 }); } // 3. 添加健康检查 builder.Services.AddHealthChecks() .AddUrlGroup(new Uri("http://your-model-service-host:port/health"), name: "model_service_health"); // 检查下游模型服务健康 // 添加其他服务... builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); var app = builder.Build(); // 配置健康检查端点 app.MapHealthChecks("/health"); // 其他中间件配置... if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); } app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.Run();

这段代码做了三件重要的事：

绑定配置：把appsettings.json里的配置映射到ModelServiceOptions类。
注册弹性HttpClient：为ModelInvokerService注册一个专用的HttpClient，并为其附加了重试和熔断策略。这样，当模型服务暂时不可用或响应缓慢时，我们的服务能优雅地应对，而不是一直阻塞或拖垮自己。
添加健康检查：我们添加了一个健康检查，它不仅可以检查我们自身服务的状态，还可以主动探测下游模型服务的健康端点（如果模型服务提供了的话）。这对于Kubernetes这样的编排系统非常有用。

3.2 创建API控制器

现在，我们需要对外暴露一个API端点。在Controllers文件夹下，创建一个ModelInvokerController.cs。

using Microsoft.AspNetCore.Mvc; using ModelInvoker.Microservice.Models; using ModelInvoker.Microservice.Services; namespace ModelInvoker.Microservice.Controllers; [ApiController] [Route("api/[controller]")] public class ModelInvokerController : ControllerBase { private readonly IModelInvokerService _modelService; private readonly ILogger<ModelInvokerController> _logger; public ModelInvokerController(IModelInvokerService modelService, ILogger<ModelInvokerController> logger) { _modelService = modelService; _logger = logger; } [HttpPost("generate")] [ProducesResponseType(typeof(ModelResponse), StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes.Status502BadGateway)] public async Task<IActionResult> GenerateText([FromBody] ModelRequest request) { if (request == null || string.IsNullOrWhiteSpace(request.Prompt)) { return BadRequest("Prompt cannot be empty."); } try { var response = await _modelService.GenerateTextAsync(request); return Ok(response); } catch (HttpRequestException ex) { _logger.LogError(ex, "Failed to communicate with the model service."); // 返回502 Bad Gateway，表示网关（即本服务）从上游服务器（模型服务）收到了无效响应。 return StatusCode(StatusCodes.Status502BadGateway, "Model service is temporarily unavailable."); } catch (TimeoutException ex) { _logger.LogError(ex, "Request to model service timed out."); return StatusCode(StatusCodes.Status504GatewayTimeout, "Model service request timed out."); } catch (Exception ex) { _logger.LogError(ex, "An internal error occurred while processing the request."); return StatusCode(StatusCodes.Status500InternalServerError, "An internal server error occurred."); } } }

这个控制器很简单，它接收一个包含prompt的请求体，调用我们刚才写的ModelInvokerService，然后返回结果。同时，它进行了基本的输入验证，并将服务层可能抛出的特定异常（如HttpRequestException,TimeoutException）转换为对客户端更友好的HTTP状态码。

4. 容器化部署与运行

微服务的最佳实践之一就是容器化。我们为这个服务创建一个Dockerfile，让它能在任何支持Docker的环境中运行。

在项目根目录下，创建一个名为Dockerfile的文件（没有扩展名）：

# 使用ASP.NET Core运行时镜像作为基础 FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base WORKDIR /app EXPOSE 8080 EXPOSE 8081 # 使用SDK镜像来构建应用 FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /src COPY ["ModelInvoker.Microservice.csproj", "./"] RUN dotnet restore "ModelInvoker.Microservice.csproj" COPY . . WORKDIR "/src/." RUN dotnet build "ModelInvoker.Microservice.csproj" -c Release -o /app/build # 发布应用 FROM build AS publish RUN dotnet publish "ModelInvoker.Microservice.csproj" -c Release -o /app/publish /p:UseAppHost=false # 最终运行镜像 FROM base AS final WORKDIR /app COPY --from=publish /app/publish . # 创建一个非root用户来运行应用，更安全 USER $APP_UID ENTRYPOINT ["dotnet", "ModelInvoker.Microservice.dll"]

现在，你可以使用以下命令来构建和运行这个Docker镜像：

# 在项目根目录（Dockerfile所在目录）执行 docker build -t model-invoker-service . # 运行容器，将容器的8080端口映射到主机的5000端口，并传入生产环境配置 docker run -d -p 5000:8080 \ -e ASPNETCORE_ENVIRONMENT=Production \ -e ModelService__BaseUrl=http://your-model-service-host:port/v1 \ -e ModelService__ApiKey=your-secure-api-key \ --name my-model-invoker \ model-invoker-service

注意，我们通过-e参数传递了环境变量来覆盖appsettings.json中的配置。在实际生产环境中，这些敏感信息应该通过更安全的方式管理，比如Docker Secrets、Kubernetes Secrets或云服务商提供的密钥管理服务。

5. 总结与展望

走完这一趟，你会发现，在.NET Core里封装一个AI模型调用服务，核心远不止是发一个HTTP请求那么简单。我们实际上构建了一个具备生产就绪特性的微服务组件：它通过IHttpClientFactory管理资源，通过Polly应对外部故障，通过健康检查汇报状态，并且可以轻松地容器化部署。

这个服务现在可以作为一个独立的进程运行，也可以被其他微服务通过HTTP调用。你可以把它部署到Kubernetes集群中，让它享受自动扩缩容、服务发现和负载均衡的好处。后续，你还可以根据需求继续增强它，比如加入更详细的监控指标（使用Prometheus）、分布式追踪（使用OpenTelemetry）、或者缓存层来缓存一些常见的模型输出以提升性能。

最重要的是，这个模式提供了一种清晰的架构分离。你的业务逻辑微服务不再需要关心如何与复杂的模型API直接交互，它们只需要调用这个封装好的“模型调用微服务”即可。这样，当模型服务升级、地址变更或认证方式改变时，你只需要更新这一个服务，而不是修改所有调用方。这种解耦，对于长期维护和迭代来说，价值巨大。