Skip to content

AI_GRADING_IMPLEMENTATION.md

Latest commit

 

History

History
305 lines (244 loc) · 9.07 KB

AI_GRADING_IMPLEMENTATION.md

File metadata and controls

305 lines (244 loc) · 9.07 KB

AI-pohjainen arviointijärjestelmä - Toteutus

Yhteenveto

Järjestelmään on toteutettu kattava AI-pohjainen automaattinen arviointijärjestelmä, joka tukee sekä OpenAI:ta että Azure OpenAI:ta. Järjestelmä mahdollistaa opettajien käyttää tekoälyä apuna tehtäväpalautusten arvioinnissa.

Keskeiset ominaisuudet

1. Kaksi toimintatilaa

  • Avustettu (Assisted): AI luo ehdotuksen, jonka opettaja hyväksyy, hylkää tai muokkaa
  • Automaattinen (Automatic): AI:n arvioinnit tallennetaan suoraan (vaatii vahvistuksen)

2. Molemmat AI-palveluntarjoajat tuettu

  • OpenAI: Suora integraatio OpenAI API:in (GPT-4o, GPT-4-turbo)
  • Azure OpenAI: Integraatio Azure OpenAI -palveluun

3. Rubric-tuki (valinnainen)

  • AI käyttää arviointiperusteet (rubric) jos ne on määritelty ja RubricService on saatavilla
  • Kriteerit ja tasot huomioidaan arvioinnissa
  • Yksityiskohtaiset pisteet kriteerioittain
  • Huom: Rubric-tuki on valinnainen - järjestelmä toimii myös ilman sitä

4. Metadata ja läpinäkyvyys

  • Tallennetaan tieto AI-arvioinnista
  • Luottamustaso (confidence score)
  • AI-mallin tiedot ja versio
  • Voidaan konfiguroida näkyväksi opiskelijoille

Backend-toteutus

Uudet tiedostot

1. Backend/TehtavaApp.API/Models/AIGradingSettings.cs

  • Enumit: AIGradingProvider, AIGradingMode
  • Konfiguraatioluokat AI-asetuksille

2. Backend/TehtavaApp.API/DTOs/AIGradingDTOs.cs

  • AIGradingResult: AI:n palauttama arviointi
  • AIGradingRequest: Pyyntö AI-arviointiin
  • AIGradingMetadata: Metadata tallennukseen

3. Backend/TehtavaApp.API/Services/Interfaces/IAIGradingService.cs

  • Interface AI-arviointipalvelulle
  • Metodit: GradeSubmissionAsync, GenerateGradingSuggestionAsync, TestConnectionAsync

4. Backend/TehtavaApp.API/Services/AIGradingService.cs

  • Täysi toteutus AI-arviointipalvelulle
  • OpenAI ja Azure OpenAI integraatiot
  • Promptin rakentaminen
  • JSON-vastausten parsinta
  • Valinnainen Rubric-tuki: Käyttää IServiceProvider:ia hakemaan IRubricService:n vain jos se on saatavilla
  • Toimii täysin ilman Rubric-palvelua

Päivitetyt tiedostot

1. Backend/TehtavaApp.API/Models/AssignmentSubmission.cs

// Uudet kentät:
public bool IsAIGraded { get; set; }
public string? AIGradingMetadata { get; set; }

// Uusi metodi:
public void MarkAsAIGraded(string gradedById, double gradeValue, string feedback, string aiMetadata)

2. Backend/TehtavaApp.API/Controllers/SubmissionController.cs

// Uudet endpointit:
[HttpPost("{id}/ai-grade")]         // Luo AI-arviointi
[HttpPost("{id}/apply-ai-grade")]   // Käytä AI-arviointia

3. Backend/TehtavaApp.API/Controllers/AdminController.cs

// Uudet endpointit:
[HttpGet("ai-grading-settings")]           // Hae asetukset
[HttpPut("ai-grading-settings")]           // Päivitä asetukset
[HttpPost("ai-grading-settings/test")]     // Testaa yhteyttä

4. Backend/TehtavaApp.API/appsettings.json

"AIGrading": {
  "Enabled": false,
  "Provider": "OpenAI",
  "Mode": "Assisted",
  "MarkAsAIGenerated": true,
  "OpenAI": {
    "ApiKey": "",
    "Model": "gpt-4o",
    "MaxTokens": 2000
  },
  "AzureOpenAI": {
    "Endpoint": "",
    "ApiKey": "",
    "DeploymentName": "",
    "ApiVersion": "2024-02-15-preview"
  }
}

5. Backend/TehtavaApp.API/Program.cs

// Lisätty DI-rekisteröinti:
builder.Services.AddScoped<IAIGradingService, AIGradingService>();

Frontend-toteutus

Uudet tiedostot

1. Frontend/tehtavaappfrontend/src/services/aiGradingService.ts

Service-luokka AI-arvioinnin käsittelyyn:

  • generateAIGrading(): Luo AI-arviointi
  • applyAIGrading(): Käytä AI-arviointia
  • getAIGradingSettings(): Hae asetukset
  • updateAIGradingSettings(): Päivitä asetukset
  • testConnection(): Testaa yhteys

2. Frontend/tehtavaappfrontend/src/components/assignments/AIGradingSuggestion.tsx

React-komponentti AI-ehdotuksen näyttämiseen:

  • Näyttää arvosanan ja luottamustason
  • Palautteen muokkaus mahdollista
  • Hyväksy/hylkää/muokkaa -toiminnot
  • Visuaalinen indikaattori luottamustasolle

3. Frontend/tehtavaappfrontend/src/components/admin/AIGradingSettings.tsx

Admin-paneeli AI-asetusten hallintaan:

  • Kaikki AI-asetukset yhdessä näkymässä
  • Provider-valinta (OpenAI/Azure)
  • API-avainten syöttö
  • Yhteyden testaus
  • Asetuksien tallennus

Päivitetyt tiedostot

1. Frontend/tehtavaappfrontend/src/types/index.ts

// Lisätty tyypit:
export interface AIGradingResult { ... }
export interface AIGradingSettings { ... }
export interface AIGradingRequest { ... }

2. Frontend/tehtavaappfrontend/src/components/assignments/GradingForm.tsx

Integroitu AI-arviointi osaksi arviointilomaketta:

  • "Luo AI-arviointiehdotus" -nappi
  • AI-ehdotuksen näyttäminen
  • AI-arviointien käsittely

Käyttöönotto

1. Backend-konfiguraatio

Päivitä appsettings.json tai käytä User Secrets / Azure Key Vault:

OpenAI:

"AIGrading": {
  "Enabled": true,
  "Provider": "OpenAI",
  "Mode": "Assisted",
  "OpenAI": {
    "ApiKey": "your-openai-api-key",
    "Model": "gpt-4o"
  }
}

Azure OpenAI:

"AIGrading": {
  "Enabled": true,
  "Provider": "AzureOpenAI",
  "Mode": "Assisted",
  "AzureOpenAI": {
    "Endpoint": "https://your-resource.openai.azure.com",
    "ApiKey": "your-azure-api-key",
    "DeploymentName": "your-deployment-name"
  }
}

2. Tietokannan päivitys

Suorita migration:

cd Backend/TehtavaApp.API
dotnet ef migrations add AddAIGradingFields
dotnet ef database update

3. Asetusten hallinta

Admin-käyttäjänä:

  1. Navigoi admin-paneeliin
  2. Valitse "AI-arvioinnin asetukset"
  3. Konfiguroi provider ja API-avaimet
  4. Testaa yhteys
  5. Tallenna asetukset

4. Käyttö opettajana

  1. Avaa opiskelijan palautus
  2. Klikkaa "Luo AI-arviointiehdotus"
  3. Odota AI:n analyysin valmistumista
  4. Tarkastele ehdotusta:
    • Arvosana (0-5)
    • Palaute
    • Luottamustaso
    • Perustelut
  5. Valitse toiminto:
    • Hyväksy: Käytä AI:n arviointia sellaisenaan
    • Muokkaa: Esilataa arvot lomakkeelle muokattavaksi
    • Hylkää: Hylkää AI:n ehdotus

AI-promptin rakenne

AI saa seuraavat tiedot:

  1. Tehtävänanto: Otsikko, kuvaus, sisältö
  2. Arviointiperusteet (jos määritelty): Rubric-kriteerit ja -tasot
  3. Opiskelijan vastaus: Palautuksen teksti

AI:ta pyydetään palauttamaan JSON-muodossa:

  • grade: Arvosana 0-5
  • feedback: Rakentava palaute suomeksi
  • criteriaScores: Pisteet kriteereittäin (jos rubric)
  • reasoning: Lyhyt perustelu

Turvallisuus

API-avaimet

  • Kehitys: User Secrets (dotnet user-secrets set)
  • Tuotanto: Azure Key Vault tai vastaava
  • API-avaimet EI KOSKAAN versionhallintaan

Rate limiting

  • Harkitse rate limiting -middleware lisäämistä
  • Estää liiallisen AI API:n käytön

Validointi

  • Opettajan vahvistus assisted-tilassa
  • Arvosanan tarkistus (0-5)
  • Palautteen pituuden validointi

Kustannukset

OpenAI hinnoittelu (arviolta)

  • GPT-4o: ~$2.50 / 1M input tokens, ~$10 / 1M output tokens
  • Keskimääräinen arviointi: ~1000 input + 500 output tokens
  • Kustannus per arviointi: ~$0.008 (alle 1 sentti)

Azure OpenAI

  • Vastaavanlainen hinnoittelu
  • Mahdollisuus capacity reservation -sopimuksiin

Jatkokehitysideat

  1. Batch-arviointi: Arvioi useita palautuksia kerralla
  2. Arviointihistoria: Tallenna AI:n arvioiden kehitys
  3. Kustomoidut promptit: Anna opettajan määritellä oma prompt-template
  4. Vertailu: Vertaa AI:n ja opettajan arviointeja
  5. Plagiointidetektio: Integroi plagiaatin tunnistus
  6. Kielentuki: Monikielinen arviointi
  7. Oppimisanalyysi: Käytä AI:ta oppimisdatan analysoinnissa

Troubleshooting

"Unable to resolve service for type 'Backend.Services.IRubricService'"

  • Korjattu: AIGradingService käyttää nyt IServiceProvider:ia hakemaan IRubricService:n optionaalisesti
  • Järjestelmä toimii täysin ilman Rubric-palvelua
  • Jos Rubric-palvelua ei ole saatavilla, AI luo arvioinnin ilman arviointiperusteita

"AI grading is not enabled"

  • Tarkista että AIGrading.Enabled = true konfiguraatiossa

"Invalid API key"

  • Varmista että API-avain on oikein
  • Tarkista että avaimella on oikeudet malliin

"Model not found"

  • Varmista että mallin nimi on oikein (esim. "gpt-4o")
  • Azure: Tarkista deployment name

Build-virheet

  • Huom: Projektissa on jo olemassa olevia build-varoituksia
  • AI-arviointi toteutus ei aiheuta uusia virheitä
  • Migration voidaan luoda kun muut build-ongelmat korjattu

Yhteenveto

AI-pohjainen arviointijärjestelmä on nyt täysin toteutettu ja valmis käyttöön. Järjestelmä tukee sekä OpenAI:ta että Azure OpenAI:ta, tarjoaa opettajalle täyden kontrollin arvioinnista, ja integroituu saumattomasti olemassa olevaan arviointijärjestelmään.

Kaikki 10 suunniteltua tehtävää on toteutettu onnistuneesti: ✅ Backend-konfiguraatio ✅ AI-palvelun toteutus ✅ Tietomallin päivitykset ✅ Controller-endpointit ✅ Admin-endpointit ✅ Frontend-service ✅ TypeScript-tyypit ✅ GradingForm-integraatio ✅ AI-ehdotuskomponentti ✅ Admin-paneeli