C# 개발자를 위한 AIMLCode 실습 가이드
.NET 8부터 ML.NET · LLM · RAG · Qdrant · MCP까지
GitHub의 AIMLCode 저장소를 직접 분석해 무엇을 설치하고, 어떤 프로젝트를 실행하며, API Key와 Qdrant/Ollama를 어떻게 연결하는지 실제 소스 구조를 기준으로 정리한 실습 가이드입니다.
이 글에서 먼저 알아둘 것
이 저장소는 하나의 완성된 AI 애플리케이션이라기보다 C# 개발자가 AI/ML 개념을 단계적으로 실습하기 위한 여러 Lab과 예제 프로젝트를 모아놓은 저장소에 가깝습니다.
README에서도 핵심 영역을 MachineLearningClass, MCPClient, MCPServerDotNet, AzureAIGuardRail, GenericEmbeddingAndChatClient 등으로 구분하고 있습니다.
따라서 처음부터 모든 프로젝트를 실행하려고 하기보다 MachinelearningClass → LLM/Tool → Embedding/RAG → Qdrant → MCP 순서로 접근하는 것이 구조를 이해하기 쉽습니다.
1. AIMLCode 저장소는 무엇인가?
공식 저장소: github.com/iamshivkoirala-sketch/AIMLCode
저장소의 Solution 파일을 확인하면 하나의 Solution 안에 여러 .NET 프로젝트가 들어 있습니다. 대표적으로 다음 프로젝트가 확인됩니다.
| 프로젝트 | 역할 | 핵심 기술 |
|---|---|---|
| MachinelearningClass | ML/AI Lab의 중심 프로젝트 | ML.NET, Semantic Kernel, Microsoft.Extensions.AI, Qdrant |
| GenericEmbeddingClient | Embedding과 Chat Client 추상화 실습 | Microsoft.Extensions.AI, Embedding |
| InterviewAssistant | ASP.NET Core 기반 AI Interview 예제 | .NET 8, OllamaSharp, Qdrant |
| MCPClient | MCP Client 실습 | ModelContextProtocol, Ollama, Microsoft.Extensions.AI |
| MCPServerDotNet | .NET MCP Server | MCP |
| MCPServerHttp | HTTP 기반 MCP Server | ASP.NET Core / MCP |
| AzureAIGuardRail | AI 안전성 실습 | Azure AI Content Safety |
2. 가장 먼저 설치해야 하는 것
필수 환경
저장소 프로젝트가 net8.0을 대상으로 합니다.
GitHub 저장소를 Clone하기 위해 필요합니다.
Visual Studio 또는 dotnet CLI로 빌드할 수 있습니다.
일부 Lab은 OpenAI API Key가 필요합니다.
현재 .NET 10이 LTS로 제공되고 있지만 이 저장소 자체는 .NET 8을 대상으로 작성되어 있습니다. 따라서 저장소를 그대로 따라가는 첫 실습에서는 .NET 8 SDK를 사용하는 것이 가장 안전합니다. Microsoft 공식 페이지 기준 .NET 8의 최신 패치는 8.0.31이며 2026년 11월 10일까지 지원됩니다.
3. 저장소 Clone
Windows PowerShell 또는 명령 프롬프트에서 다음과 같이 시작합니다.
git clone https://github.com/iamshivkoirala-sketch/AIMLCode.git
cd AIMLCode
저장소의 기본 브랜치는 현재 main입니다. Solution 파일은 MachinelearningClass.sln입니다.
C:\Dev\AIMLCode
4. 먼저 전체 Solution을 복원한다
저장소에는 여러 프로젝트가 포함되어 있으므로 먼저 Solution 단위로 NuGet 패키지를 복원하는 것이 좋습니다.
dotnet restore MachinelearningClass.sln
그 다음 빌드합니다.
dotnet build MachinelearningClass.sln --configuration Debug
저장소에는 현재 프로젝트 코드뿐 아니라 Visual Studio의 .vs, bin, obj 계열 산출물도 포함되어 있는 흔적이 확인됩니다. 따라서 Clone 직후 기존 빌드 산출물에 의존하기보다 dotnet restore → dotnet build 순서로 현재 환경에서 다시 복원·빌드하는 것을 권장합니다.
5. 첫 번째 실행은 MachinelearningClass부터
이 저장소를 처음 접한다면 가장 먼저 확인해야 할 파일은 다음 두 개입니다.
- MachinelearningClass/Program.cs
- MachinelearningClass/AllLabs.cs
현재 Program.cs에서는 기본적으로 다음 Lab이 실행되도록 되어 있습니다.
AllLabs.Lab19ToolingusingSemanticKernel().Wait();
반대로 Qdrant RAG 예제는 현재 주석 처리되어 있습니다.
//AllLabs.Lab21_QdrantRag().Wait();
즉, 단순히 F5를 누른다고 해서 모든 AI/ML 예제가 순서대로 실행되는 구조가 아닙니다. Program.cs에서 어떤 Lab 메서드를 호출할 것인지 선택하는 방식입니다.
6. 첫 번째 AI 실습에 필요한 API Key
저장소의 여러 코드에서 다음과 같은 형태로 API Key를 읽습니다.
var apiKey = Environment.GetEnvironmentVariable("aikey");
따라서 소스 코드에 API Key를 직접 입력하지 않고 aikey라는 환경 변수를 설정해야 합니다.
Windows PowerShell
$env:aikey = "YOUR_API_KEY"
이 방식은 현재 PowerShell 세션에서만 적용됩니다. 실습 중 가장 간단하게 사용할 수 있는 방법입니다.
Windows 사용자 환경 변수로 저장
setx aikey "YOUR_API_KEY"
실제 API Key를 GitHub 소스에 하드코딩하거나 블로그에 그대로 게시하면 안 됩니다. 위 예제의 YOUR_API_KEY는 실제 키가 아닌 자리표시자입니다.
7. Lab19 — Semantic Kernel Tool Calling부터 실행해보기
저장소에서 현재 Program.cs가 호출하는 핵심 Lab 중 하나가 Lab19ToolingusingSemanticKernel()입니다.
소스를 보면 API Key를 환경 변수에서 가져온 뒤 Semantic Kernel에 OpenAI Chat Completion을 연결하고, Plugin을 등록하는 구조입니다.
var apiKey = Environment.GetEnvironmentVariable("aikey");
var kernel = Kernel.CreateBuilder()
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey)
.Build();
kernel.Plugins.AddFromType("greetingtools");
여기서 중요한 것은 특정 모델 이름 자체보다 구조입니다.
LLM을 연결한다.
AI 실행 환경을 구성한다.
C# 메서드를 AI가 사용할 수 있는 도구로 연결한다.
모델이 필요할 때 도구를 선택한다.
저장소의 코드는 gpt-4o-mini를 사용하고 있습니다. 이것은 저장소 코드에 기록된 값이지, 2026년 현재 OpenAI의 최신 모델을 의미하지 않습니다. 따라서 저장소를 그대로 재현할 때는 코드의 모델명을 유지하고, 새로운 프로젝트에 적용할 때는 현재 사용 가능한 모델과 해당 SDK 문서를 별도로 확인해야 합니다.
8. MachinelearningClass에서 배우는 ML.NET
MachinelearningClass는 단순한 LLM 예제만 있는 프로젝트가 아닙니다. 전통적인 Machine Learning부터 시작합니다.
AllLabs.cs를 보면 다음과 같은 단계가 포함되어 있습니다.
- 간단한 Regression
- 여러 Feature를 이용한 Regression
- Train/Test 데이터 분리
- R²와 RMSE 평가
- AutoML
- Model 저장
- Model Load
- Clustering
- Embedding
- RAG
- Semantic Kernel Tooling
예를 들어 저장소의 기본 ML 예제는 Age → Premium과 같은 입력/출력 관계를 이용해 모델을 학습시키는 구조입니다.
var data = mlcontext.Data.LoadFromEnumerable(
DataRegression.GetLinearInsuranceData());
var pipeline = mlcontext.Transforms
.Concatenate("Features", "Age")
.Append(
mlcontext.Regression.Trainers
.Ols(
labelColumnName: "Premium",
featureColumnName: "Features"));
var model = pipeline.Fit(data);
여기서 중요한 개념은 Data → Pipeline → Training → Model → Inference입니다.
9. Embedding을 이해하기
이 저장소에서는 LLM뿐 아니라 Embedding과 Semantic Search를 다루는 코드도 포함되어 있습니다.
Embedding은 텍스트 등의 데이터를 숫자 벡터 형태로 표현하여 의미적으로 유사한 데이터를 검색할 수 있도록 만드는 기술입니다.
10. Qdrant를 사용하는 RAG 실습
저장소에는 Qdrant.Client가 포함되어 있고, AllLabs.cs의 Qdrant 관련 코드에서는 다음과 같이 로컬 Qdrant에 접속합니다.
var client = new QdrantClient("localhost", 6334);
따라서 Qdrant RAG Lab을 실행하려면 먼저 로컬 Qdrant 서버가 실행되어 있어야 합니다.
Qdrant 설치 — Docker 권장
Qdrant 공식 문서는 개발 및 테스트 환경에서 Docker를 이용한 실행을 권장합니다.
docker pull qdrant/qdrant
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
실행 후 Qdrant의 REST API는 6333 포트, gRPC는 6334 포트를 사용합니다. 이 저장소의 C# 코드가 6334 포트를 사용하므로 6334 포트가 열려 있는지가 중요합니다.
Qdrant 공식 문서: Qdrant Local Quickstart
Qdrant 기본 로컬 실행은 인증과 암호화가 설정되지 않은 상태입니다. 개발 PC에서만 사용하는 실습 환경과 외부에 노출되는 서버 환경을 동일하게 취급하면 안 됩니다.
11. Qdrant가 정상적으로 실행되었는지 확인
브라우저에서 다음 주소를 열어 확인할 수 있습니다.
http://localhost:6333
Qdrant 공식 문서에서는 로컬 인스턴스가 6333 포트에서 REST API를 제공하고, 6334 포트에서 gRPC를 제공한다고 설명합니다.
또한 대시보드도 기본적으로 다음 주소에서 접근할 수 있습니다.
http://localhost:6333/dashboard
따라서 실습 전에 다음 상태를 확인하는 것이 좋습니다.
- Docker가 실행 중인가?
- Qdrant Container가 실행 중인가?
- localhost:6333에 접근 가능한가?
- localhost:6334 포트가 사용 가능한가?
12. Lab21_QdrantRag 실행하기
현재 Program.cs에서는 Qdrant RAG Lab이 주석 처리되어 있습니다.
//AllLabs.Lab21_QdrantRag().Wait();
Qdrant 환경을 먼저 실행한 뒤 이 호출을 활성화합니다.
AllLabs.Lab21_QdrantRag().Wait();
그리고 기존에 실행되던 Lab19 호출은 일단 주석 처리합니다.
//AllLabs.Lab19ToolingusingSemanticKernel().Wait();
AllLabs.Lab21_QdrantRag().Wait();
이후 실행합니다.
dotnet run --project MachinelearningClass/MachinelearningClass.csproj
여기서 설명하는 것은 저장소 소스 코드와 설정을 분석한 실행 절차입니다. 이 글 작성 환경에서 해당 저장소 전체를 실제 API Key와 Qdrant까지 연결해 실행한 결과는 아닙니다. 따라서 특정 콘솔 출력값을 "실측 결과"라고 주장하지 않습니다.
13. InterviewAssistant는 어떤 프로젝트인가?
저장소에는 별도의 ASP.NET Core 프로젝트인 InterviewAssistant도 있습니다.
프로젝트 파일을 보면 .NET 8을 대상으로 하고 있으며 OllamaSharp와 Qdrant.Client를 사용합니다.
dotnet run --project InterviewAssistant/InterviewAssistant.csproj
기본 Program.cs는 ASP.NET Core MVC 애플리케이션 형태입니다.
또한 ResumeController에서 Ollama 클래스를 이용해 Resume 내용을 처리하는 흐름이 확인됩니다.
다만 이 프로젝트는 단순히 dotnet run만 하면 외부 LLM까지 자동으로 구성되는 완성형 배포 시스템이라고 보면 안 됩니다. Ollama와 모델 실행 환경을 별도로 준비해야 합니다.
14. Windows에서 Ollama를 사용하는 경우
Ollama는 Windows용 공식 설치 프로그램을 제공하며, 현재 Windows 10 이상을 지원합니다.
공식 다운로드: Ollama for Windows
설치 후 Ollama 기반 프로젝트를 사용하려면 실제로 사용할 모델을 준비해야 합니다.
이 저장소의 Ollama 관련 코드는 모델명을 코드 내부에서 사용하는 부분이 있으므로, 저장소의 모델명과 현재 설치된 Ollama 모델명이 일치하는지 확인해야 합니다.
Ollama를 설치했다고 해서 모든 AI 모델이 자동으로 설치되는 것은 아닙니다. 모델 다운로드 및 메모리/GPU 요구사항은 사용하는 모델에 따라 달라집니다.
15. MCPClient는 어떻게 구성되어 있는가?
저장소에는 MCP를 별도 프로젝트로 구성해 놓았습니다.
MCPClient의 프로젝트 파일을 보면 다음과 같은 구성입니다.
- ModelContextProtocol
- Microsoft.Extensions.AI.Ollama
- OllamaSharp
- Microsoft.Extensions.Hosting
즉 이 예제는 LLM + Microsoft.Extensions.AI + MCP 구조를 C#에서 실습하기 위한 예제입니다.
저장소에는 MCPServerDotNet과 MCPServerHttp도 별도로 존재합니다.
16. .mcp.json에서 확인되는 MCP 연결 방식
저장소 루트의 .mcp.json도 확인할 수 있습니다. 여기에는 두 가지 MCP Server 연결이 정의되어 있습니다.
- SSE 방식의 MCP Server
- stdio 방식의 .NET MCP Server
특히 stdio 설정은 저장소 작성자의 로컬 Windows 경로를 직접 참조합니다.
{
"servers": {
"mcptool": {
"type": "stdio",
"command": "dotnet",
"args": [
"C:\Users\shivB\source\repos\MachinelearningClass\MCPServerDotNet\bin\Debug\net8.0\MCPServerDotNet.dll"
]
}
}
}
위 경로는 저장소 작성자의 PC 경로입니다. 다른 PC에서는 그대로 사용할 수 없습니다. 자신의 Clone 경로와 실제 빌드 결과 경로에 맞게 수정해야 합니다.
17. 전체 실행 순서 — 가장 추천하는 학습 루트
18. 프로젝트별 필요한 외부 환경
| 프로젝트 | 기본 환경 | 추가 필요 가능 항목 |
|---|---|---|
| MachinelearningClass | .NET 8 | Lab에 따라 OpenAI API, Qdrant 등 |
| GenericEmbeddingClient | .NET | Embedding Provider |
| InterviewAssistant | ASP.NET Core / .NET 8 | Ollama, Qdrant |
| MCPClient | .NET 8 | MCP Server, Ollama 또는 다른 LLM Provider |
| MCPServerDotNet | .NET 8 | MCP Client |
19. 이 저장소에서 특히 주의해야 할 부분
① 작성자의 절대 경로
소스에는 다음과 같은 로컬 경로가 존재합니다.
C:\Users\shivB\source\repos\MachinelearningClass\...
이것은 저장소를 Clone한 사용자의 경로가 아닙니다. CSV나 DLL, MCP Server 등을 참조하는 부분은 자신의 환경에 맞게 수정해야 합니다.
② 현재 기본 실행 Lab과 학습 순서는 다르다
Program.cs가 Lab19를 호출한다고 해서 Lab19가 처음 배우기에 가장 적합하다는 의미는 아닙니다. 저장소 자체가 여러 Lab을 하나의 프로젝트에 모아놓은 형태이므로 학습 순서와 Program.cs의 현재 선택은 별개로 보는 것이 좋습니다.
③ 패키지 버전은 저장소 당시의 재현 정보다
현재 MachinelearningClass.csproj에는 ML.NET 4.0.3, Microsoft.Extensions.AI 10.7.0, Microsoft.Extensions.AI.OpenAI 10.8.1, Semantic Kernel 1.70.0, OllamaSharp 5.4.25, Qdrant.Client 1.18.1 등의 버전이 기록되어 있습니다.
이것은 현재 시점의 최신 버전 목록이 아니라 해당 저장소가 현재 코드에서 참조하는 버전입니다. 그대로 재현하려면 csproj의 버전을 우선 존중하고, 새로운 프로젝트를 시작할 때는 각 공식 패키지의 현재 버전을 별도로 확인해야 합니다.
④ MCP 설정의 로컬 경로
.mcp.json에 작성자의 절대 경로가 포함되어 있기 때문에 다른 PC에서 그대로 사용하는 것은 적절하지 않습니다.
20. Microsoft.Extensions.AI가 왜 중요한가?
이 저장소에서 특히 눈여겨볼 부분은 Microsoft.Extensions.AI입니다.
Microsoft의 현재 .NET AI 추상화에서 IChatClient는 Chat 모델과 애플리케이션 사이의 공통 인터페이스 역할을 합니다.
따라서 애플리케이션 코드가 특정 AI Provider 구현에 지나치게 묶이지 않도록 구조를 분리하는 데 사용할 수 있습니다.
Application → OpenAI SDK 직접 호출
Application → IChatClient → Provider
Microsoft 공식 문서에서도 IChatClient는 Chat Client를 표현하는 인터페이스로 정의되어 있습니다.
21. 이 저장소를 실무 프로젝트에 그대로 복사하면 안 되는 이유
AIMLCode는 학습 목적의 Lab 저장소로 보는 것이 적절합니다. 실무 시스템을 만들 때는 다음 요소를 추가해야 합니다.
API Key와 Endpoint를 Secret/Configuration으로 관리
사용자가 접근할 수 있는 RAG 데이터만 검색
LLM 요청과 Tool 호출을 안전하게 추적
외부 AI Provider 장애에 대한 처리
사용자 입력과 검색된 문서를 신뢰할 수 없는 데이터로 취급
Token, 요청량, 모델별 비용 관리
특히 Microsoft의 IChatClient 문서에서도 애플리케이션이 Prompt Injection, 데이터 크기, 메시지 수 등의 위험을 적절하게 관리해야 한다는 점을 명시하고 있습니다.
22. 처음 설치하는 사람을 위한 실제 체크리스트
23. C# 개발자 관점에서 이 저장소를 보는 핵심 구조
결국 이 저장소가 보여주는 핵심은 "C#에서도 AI 모델을 호출하는 것"을 넘어 AI 시스템을 구성하는 각각의 계층을 이해하는 것입니다.
24. 개인적으로 가장 추천하는 실습 순서
저장소에 있는 모든 Lab을 처음부터 하나씩 실행하는 방식보다 다음 순서가 개념적으로 더 명확합니다.
Data → Training → Model → Prediction
2단계 — LLMC# → Chat Model → Response
3단계 — Tool CallingLLM → Tool 선택 → C# 메서드 실행
4단계 — EmbeddingText → Vector
5단계 — Vector SearchQuery Vector → Similarity Search
6단계 — RAGRetrieve → Context → LLM
7단계 — Local AIOllama → Local Model
8단계 — MCPAI Application → MCP Client → External Tool/Server
25. 결론 — AIMLCode는 "완성품"보다 "AI 개발 커리큘럼"으로 보는 것이 좋다
AIMLCode의 가장 큰 특징은 하나의 프레임워크만 설명하는 것이 아니라 C# 개발자가 AI/ML 영역으로 넘어갈 때 만나는 여러 기술을 하나의 저장소에서 확인할 수 있다는 점입니다.
ML.NET으로 전통적인 Machine Learning의 기본 구조를 이해하고, Semantic Kernel로 LLM과 Tool을 연결하고, Embedding과 Qdrant로 RAG를 이해한 다음, Ollama로 Local AI를 경험하고, 마지막으로 MCP를 통해 AI가 외부 도구와 시스템을 연결하는 구조까지 확장할 수 있습니다.
특히 기존 C#/.NET 개발자라면 Python부터 다시 시작하기보다 현재 알고 있는 .NET DI, Interface, Middleware, Service, API 구조에 AI 구성요소를 어떻게 결합하는가라는 관점에서 접근하는 것이 이 저장소를 이해하는 데 도움이 됩니다.
AIMLCode는 "AI를 한 번에 완성하는 프로젝트"가 아니라 ML → LLM → Tool → Embedding → RAG → Local AI → MCP 로 이어지는 C# AI 개발의 실습 지도를 제공하는 저장소로 보는 것이 가장 정확합니다.
FAQ
Q. Visual Studio가 반드시 필요한가?
아닙니다. 저장소는 .NET 프로젝트이므로 dotnet CLI로 restore/build/run할 수 있습니다. 다만 Solution과 여러 프로젝트를 함께 확인하려면 Visual Studio가 편리합니다.
Q. 처음부터 Qdrant를 설치해야 하나?
아닙니다. 기본 ML Lab이나 일부 LLM Lab을 먼저 실행한다면 Qdrant가 필요하지 않을 수 있습니다. Qdrant RAG Lab을 실행할 때 준비하면 됩니다.
Q. OpenAI API Key가 모든 프로젝트에 필요한가?
아닙니다. 프로젝트와 Lab에 따라 다릅니다. MachinelearningClass의 여러 예제는 OpenAI API Key를 환경 변수 aikey에서 읽지만, Ollama를 사용하는 예제는 로컬 모델 구성이 별도로 필요합니다.
Q. .mcp.json을 그대로 사용하면 되는가?
아닙니다. 현재 파일에는 작성자의 Windows 절대 경로가 포함되어 있습니다. 자신의 Clone 및 빌드 경로에 맞게 수정해야 합니다.
Q. 이 저장소의 패키지 버전을 최신 버전으로 바로 올려도 되는가?
권장하지 않습니다. 먼저 저장소에 기록된 버전으로 재현한 후, 패키지를 하나씩 업그레이드하면서 호환성을 확인하는 것이 안전합니다.
출처 및 공식 문서
작성 기준일: 2026-09-17. 이 글의 저장소 관련 내용은 해당 시점의 AIMLCode main 브랜치 소스와 프로젝트 파일을 기준으로 분석했습니다. 패키지 버전, AI 모델, API, Qdrant/Ollama 동작 방식은 이후 변경될 수 있으므로 실제 적용 전 공식 문서를 다시 확인해야 합니다. 저장소의 일부 코드는 작성자의 로컬 환경을 전제로 한 절대 경로를 포함하고 있으므로 그대로 복사해서는 안 됩니다.
댓글
댓글 쓰기