How to Design Real AI Agents (Agents)?

Transitioning from "Persona" to Tool-Using Decision Mechanisms
A step-by-step senior-level AI Engineer guide from Level 0 to Level 7.

Published: June 2026  |  Reading time: ~25 min  |  Category: AI Engineering

🎯 Introduction: Why "You Are the Best AI Engineer in the World" Is Not Enough

90% of online tutorials tell you to write this to create an agent:

"You are the best software engineer in the world..."

If you are deploying an application to production, prompts written with only persona will turn your system into a hallucination bomb.

The real power of agents does not come from the roles you assign them; it comes from Tool Calling, Grounding, and Explainability.

💡 What Will You Learn in This Post?

In this post we will take a simple problem — "measuring text similarity" — and show you step by step how to evolve it from a novice approach to an autonomous level designed by a senior AI Engineer. At each level we will compare prompts, architecture, and cost.

🎬 Learn with Video: Murat Karakaya Akademi

You can also watch this training on the Murat Karakaya Akademi YouTube channel. Follow the same journey from Level 0 to Level 7 with step-by-step live demos, code explanations, and architectural analysis.

▶ Watch on YouTube — Murat Karakaya Akademi

📌 Level 0 — Novice Approach: Black Box & Hallucination

Beginner

Scenario: We need to find how similar Text 1 and Text 2 are on a 0–100 scale. (For example, in a RAG system, we measure how faithfully a generated answer stays true to the reference text).

Novice Prompt:
"You are a text analyst. Compare the given Text 1 and Text 2 and decide how similar they are. Return the similarity as a numeric value between 0–100. 0: They do not match at all, 100: They are completely identical word for word."

Why Is This Bad?

1. Black Box: The model only returns "75". Why 75? Not 74 or 80? We don't know.
2. Subjectivity: The same texts might get 60 one day and 85 the next.
3. Hallucination Risk: LLMs cannot perform mathematical measurements; they predict words. "75" is a fabricated (hallucinated) value.

📌 Level 1 — Structured Output & Chain of Thought

Improvement

The first thing we want is Explainability. We tell the model: "Don't just give me the result, show me your thinking process."

"You are a text analyst. Your goal is to measure the semantic similarity between two texts. Your output MUST be a valid JSON object. Do not use Markdown or additional text. Required JSON fields: - reasoning: The specific justification for similarity and differences between these two texts. - similarity_score: An integer between 0-100. Expected JSON schema: { "type": "object", "required": ["reasoning", "similarity_score"], "properties": { "reasoning": {"type": "string"}, "similarity_score": {"type": "integer", "minimum": 0, "maximum": 100} } }"

Why Is This Better?

• Chain of Thought: We did not ask for the score first. We asked it to fill the reasoning field first. The model justifies its own inference while writing the explanation.
• Debugging: If the score is 40, we can look at the logs and say "The model missed this detail, that's why it gave a low score."
• Integration: The JSON output can be parsed by application code.

⚠️ What Is Missing: The score is still subjective. The 0–100 scale is too broad and unstructured for an LLM.

📌 Level 2 — Rubric and Objectivity (Divide & Conquer)

Increased Autonomy

We are not allowing the agent to interpret the abstract concept of "similarity" on its own. We give it rules (rubric). We break the problem into parts.

Rubric:

• 1. Main Idea (0-20): Do both texts convey the same core message?
• 2. Tone and Style (0-20): Do the texts have the same formality and emotion?
• 3. Entities (0-20): Do the names, dates, and numbers in the texts match?
• 4. Missing Information (0-20): Does Text 2 omit an important detail from Text 1?
• 5. Fluency (0-20): How structurally coherent is Text 2?

"You are an expert evaluator. Evaluate the two texts according to the 5 criteria below. Each criterion is scored 0-20. Your output MUST be a valid JSON object. Do not use Markdown or additional text. Required JSON fields: - evaluations: A list of 5 items [criterion, score, explanation] - total_score: The sum of the five criterion scores. Expected JSON schema: { "type": "object", "required": ["evaluations", "total_score"], "properties": { "evaluations": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "object", "required": ["criterion", "score", "explanation"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"} } } }, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }"

Why Is This Better?

• Grounding: We removed the model from abstract evaluation on a scale of 100.
• Objectivity: Scores will be much more consistent even if you run them at different times (variance decreases).
• Comparability: We can evaluate different prompts against the same rubric.

📌 Level 3 — Example-Based Rubric Calibration (One-Shot / Few-Shot)

Calibration

In Level 2 we gave the rubric; however, this was still zero-shot prompting. The model read the criteria but never saw from examples what "When do I give 20 points?", "What is the boundary case for 10?", "When is 0 appropriate?"

At this level we provide small, representative-examples for each criterion.

Scoring Calibration Examples:

• Main Idea — 20 points: "Data cleaning is critical for model success" and "Model quality heavily depends on clean data" convey the same core message.
• Main Idea — 10 points: Both texts discuss data quality but one focuses on security risks while the other focuses on model performance.
• Main Idea — 0 points: One discusses data cleaning, the other discusses a sports match result.
• Tone and Style — 20 points: Both texts are written in an academic and formal tone.
• Tone and Style — 10 points: One is formal, the other more conversational, but the meaning is preserved.

Why Is This Better?

• Consistency: The model uses the same score ranges more reliably.
• Teachability: The rubric is now supported by behavioral examples, not just an abstract list.
• Cost: Few-shot examples increase input tokens — so examples must be short and clear.

Expected JSON Schema:

{ "type": "object", "required": ["evaluations", "calibration_note", "total_score"], "properties": { "evaluations": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "object", "required": ["criterion", "score", "explanation"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"} } } }, "calibration_note": {"type": "string"}, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }

📌 Level 4 — Tool Calling and Workflow

Grounding Begins

In Level 3 we calibrated the rubric with examples; however, the evaluation still relied solely on LLM interpretation. Now we add deterministic metrics from external systems as evidence.

Metrics Used:

• ROUGE-L F1: Measures word-sequence overlap.
• Lightweight Similarity Score: A combination of Token cosine + Token Jaccard + Character 3-gram cosine + Sequence ratio.

Metric Interpretation Rules:

• If ROUGE-L F1 is low, this indicates low word-sequence overlap; it is not alone evidence of low semantic similarity.
• If the Lightweight Similarity Score is higher than ROUGE-L, the texts may convey a similar message with different words.
• The Lightweight Similarity Score is not a real semantic embedding; it should be used as a decision-support signal, not as the sole decision-maker.

🌍 Why Is This Used in the Real World?

• Reliability: ROUGE and lightweight similarity scores are deterministic — they give the same scores to the same text pair every time.
• Traceability: Since the LLM's opinion is grounded in external evidence, evaluation becomes more auditable.
• Cost Control: Lightweight metrics are fast and do not require heavy model dependencies.

🔬 Experiment Hygiene Note

Level 4 uses the same rubric text as Level 3. This is a deliberate decision: the difference between the two levels is not a rubric change, but only external metric context.

Additional Required JSON Fields in Level 4:

• metric_interpretation: Explain how you interpreted the ROUGE-L F1 and Lightweight Similarity Score values.
• calibration_note: Explain how the rubric calibration examples affected your scoring.

Expected JSON Schema (Level 4):

{ "type": "object", "required": ["evaluations", "metric_interpretation", "calibration_note", "total_score"], "properties": { "evaluations": { /* Same 5-item list as Level 3 */ }, "metric_interpretation": {"type": "string"}, "calibration_note": {"type": "string"}, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }

📌 Level 5 — ReAct and Ollama Tool Calling with Real Agent Loop

Real Agentic Loop

We built a strong workflow in Level 4, but was our system a real agent? Not exactly. Because we calculated the metrics with Python. In real agent behavior, the model determines what evidence it needs, the software layer executes the tool, and the result returns to the model.

ReAct Loop:

• Reasoning: The model determines what external evidence it needs to evaluate text similarity.
• Action: Instead of writing plain text, the model produces Ollama's native tool_calls field.
• Observation: Python executes the relevant function and returns the result to the model as role="tool".
• Final Answer: The model uses the tool results to produce the rubric-based JSON evaluation.

Ollama Native Tool Calling Flow:

1. Functions are presented to the model via the `tools=[...]` list. 2. If needed, the model produces `response.message.tool_calls`. 3. Python executes these tool calls. 4. Results are added to the conversation as `role="tool"` messages. 5. The model produces the final answer based on tool results.

Tool Definitions (Python):

def calculate_rouge_tool(reference_text: str = "", candidate_text: str = "") -> str: """Calculate ROUGE scores.""" return json.dumps(calculate_rouge(METIN_1, METIN_2), ensure_ascii=False) def calculate_lightweight_similarity_tool(reference_text: str = "", candidate_text: str = "") -> str: """Calculate lightweight similarity score for the fixed Text 1 and Text 2 in the notebook. Args: reference_text: Not considered in training demo; tool uses fixed METIN_1. candidate_text: Not considered in training demo; tool uses fixed METIN_2. Returns: JSON string containing Token cosine, Token Jaccard, character 3-gram cosine, sequence ratio, and combined score. """ return json.dumps(calculate_lightweight_similarity(METIN_1, METIN_2), ensure_ascii=False)

Tool Calling Loop (Pseudo-Python):

messages = [ {"role": "system", "content": TOOL_CALLING_SYSTEM_PROMPT}, {"role": "user", "content": "Text 1: ..., Text 2: ..."}, ] while True: response = client.chat( model=MODEL, messages=messages, tools=[calculate_rouge_tool, calculate_lightweight_similarity_tool], ) messages.append(response.message) if not response.message.tool_calls: print(response.message.content) # Final answer break for tool_call in response.message.tool_calls: tool_name = tool_call.function.name result = available_tools[tool_name](**tool_call.function.arguments) messages.append({ "role": "tool", "tool_name": tool_name, "content": str(result), })

Why Is This a Mastery-Level Skill?

• ReAct is not just writing Thought / Action / Observation; it is connecting thought to real tool execution.
• An agent is the joint design of prompt, tool calling, execution loop, grounding, and error control layers.
• The model determines tool needs, Python executes the tool, and the final evaluation is supported by external evidence.

📊 Level 5 Token Cost:

"Since Level 5 is a multi-turn agent loop, the input token is not just the length of the first user prompt. With each client.chat call, the system message, user message, previous assistant messages, and tool results are re-injected into context. Therefore, the input token total in Level 5 is not a unique token count, but a cumulative processed token / cost indicator."

🛡️ In the Real World: Production Guardrails

In real production, these protections are added: schema validation, maximum step limit, tool allowlist, retry, and tracing/logging.

Level 5 Tool Calling JSON Schema:

{ "type": "object", "required": ["evaluations", "metric_interpretation", "calibration_note", "total_score"], "properties": { "evaluations": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "object", "required": ["criterion", "score", "explanation"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"} } } }, "metric_interpretation": {"type": "string"}, "calibration_note": {"type": "string"}, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }

📌 Level 6 — Rubric-Based Sub-Agents and Python Aggregator

Modular Architecture

In Level 5, a single agent both called tools and interpreted the entire rubric on its own. At this level we try a different architecture: instead of one large prompt, we give each rubric criterion to a separate sub-agent.

Architecture:

• 1 generic sub-agent function is written.
• This function is called 5 times with 5 different rubric configurations.
• Each sub-agent evaluates only its own criterion.
• Python aggregator validates, sorts, and calculates the total score.
• The aggregator makes no LLM calls — it is deterministic.

The Pedagogical Message of This Level:

✅ "Don't make everything an agent!"
LLM is for subjective evaluation. Python is for validation, aggregation, formatting, and deterministic computation.

Limitations:

• 5 sub-agents = 5 LLM calls = more expensive than Level 5.
• Not necessary in every case; it makes sense when the rubric grows or when audibility is critical.

Level 6 — Sub-Agent JSON Output (single criterion):

{ "criterion": "Main Idea", "score": 18, "explanation": "Specific evaluation for this criterion", "evidence": "Basis from text or metrics" }

Python Aggregator Total Output (all criteria):

{ "evaluations": [ {"criterion": "Main Idea", "score": 18, "explanation": "...", "evidence": "..."}, {"criterion": "Tone and Style", "score": 16, "explanation": "...", "evidence": "..."}, {"criterion": "Entities", "score": 17, "explanation": "...", "evidence": "..."}, {"criterion": "Missing Information", "score": 15, "explanation": "...", "evidence": "..."}, {"criterion": "Fluency", "score": 14, "explanation": "...", "evidence": "..."} ], "metric_interpretation": "ROUGE and lightweight similarity metrics were provided as context to each sub-agent; each criterion was interpreted by its own expert sub-agent.", "aggregation_note": "Total score was computed deterministically by the Python aggregator; no LLM orchestrator was used.", "total_score": 80 }

Level 6 Python Aggregator Function Example:

def aggregate_sub_agent_results(sub_agent_results, metrics_context): expected_criteria = [config['criterion'] for config in RUBRIC_AGENT_CONFIGS] actual_criteria = [result['parsed'].get('criterion') for result in sub_agent_results] if actual_criteria != expected_criteria: raise ValueError(f"Sub-agent criterion order does not match expected.") evaluations = [] for result in sub_agent_results: parsed = result['parsed'] score = parsed.get('score') if not isinstance(score, int) or not 0 <= score <= 20: raise ValueError(f"Invalid score: {parsed}") evaluations.append({ 'criterion': parsed['criterion'], 'score': score, 'explanation': parsed['explanation'], 'evidence': parsed['evidence'], }) total_score = sum(item['score'] for item in evaluations) return { 'evaluations': evaluations, 'metric_interpretation': '...', 'aggregation_note': 'Total score was computed deterministically by Python.', 'total_score': total_score, }

Level 6 — Token Cost:

• 5 sub-agents = 5 independent LLM calls
• Each call includes system prompt + user prompt + metric context
• Total input token = 5 × (system + user prompt length)
• Aggregator token cost = 0 (Python code runs)

Level 6 — Sub-Agent JSON Schema (inside build_sub_agent_system_prompt):

{ "type": "object", "required": ["criterion", "score", "explanation", "evidence"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"}, "evidence": {"type": ["string", "array", "object"]} } }

📌 Level 7 — Orchestrator Agents and When They Are Not Needed

Architectural Decision

After Level 6 the natural question is: "Wouldn't it be better if an orchestrator agent managed these sub-agents?"

Orchestrator Agent is a powerful architecture in the real world. An orchestrator can break down tasks, decide which sub-agent to run, select appropriate tools, initiate retries on missing or contradictory results, and convert results from different agents into a final decision.

However, in this example we deliberately do not need it, because:

• The 5 rubric criteria are predetermined.
• Every criterion must run.
• Each sub-agent evaluates only its own criterion.
• Missing criterion check, sorting, and total score can be reliably done with Python.

🏗️ When Does an Orchestrator Agent Make Sense?

• When which sub-agents to run changes from task to task.
• When tool selection, data source selection, or workflow branching is needed.
• When there are contradictions between sub-agent responses and an interpretive reconciliation is needed.
• When there are dynamic steps such as quality control, retry, missing information completion, or human approval.

Level 7's Message: Orchestrator + sub-agent architectures exist and are important; however, they are not necessary in every problem. In this example, the Python aggregator is the correct, simple, and instructive choice.

💡 Level 7 Note: This level does not make a new LLM call. It is an architectural decision-making and boundary-setting section. Performance graphs show the cost of Level 0-6 experiments.

📊 Comparison of All Levels

Level	Approach	Added Layer	Gain	Limitation / Lesson
Lvl 0	Persona / Black Box	Simple system prompt	Fast start	Inconsistent, unexplainable, hallucination-prone
Lvl 1	JSON + Explanation	Structured output	Answer becomes parseable	Still subjective
Lvl 2	Rubric	Criteria-based evaluation	More objective score	No external evidence, still LLM opinion
Lvl 3	One-Shot / Few-Shot Calibration	Criteria-based examples	More consistent scores	Input token cost increases
Lvl 4	Workflow + Tools	ROUGE + lightweight similarity metrics	Grounded, evidence-based	Developer selects the tools
Lvl 5	ReAct + Tool Calling	Automatic tool calling + execution loop	Real agent behavior	High cost, loop management needed
Lvl 6	Sub-Agents + Python Aggregator	Generic sub-agent + deterministic aggregation	Task decomposition, responsibility separation	5× LLM calls, more expensive
Lvl 7	Orchestrator Agent Decision	Architectural decision-making	Understanding of advanced architectures	Orchestrator not needed everywhere

🎓 Final Message: Prompt Engineering Becomes Systems Engineering

Simply giving an agent a powerful-sounding prompt and expecting it to work correctly is not enough.
A Real AI Agent is not just a model that produces answers; it is a software system that jointly manages thinking patterns, tool usage, reasoning steps, and data-driven evidence.

As we progressed from Level 0 to Level 7, we actually built the same idea layer by layer. First we structured the output, then we broke evaluation into rubric parts, then we calibrated with examples. Then we added grounding with metrics and connected the ReAct idea to real tool execution. Finally, we saw that more advanced architectures like orchestrator agents exist, but in this example, not adding an extra LLM orchestrator was the more correct engineering decision.

Our value as AI Engineers emerges here: instead of expecting miracles from the model, understand the model's strengths and weaknesses and build the right architecture around them. Good agent design is not just about writing prompts; it is about proving with data, supporting with tools, making reasoning visible, and making outputs measurable.

📝 Test Texts Used in the Training

These two texts were specifically selected: low word overlap (low ROUGE), yet they convey a semantically similar message.

Text 1 (Reference):
"In the process of training artificial intelligence models, the use of high-quality datasets is of critical importance. If the dataset contains incorrect, biased, or incomplete information, the results produced by the model will inevitably be flawed and unreliable. Therefore, data cleaning is a more prioritized step than the complexity of the model architecture."

Text 2 (System Output):
"The success of machine learning algorithms heavily depends on the quality of the information they are fed. Algorithms fed with dirty, biased, or incomplete data will naturally produce incorrect and untrustworthy outputs. Therefore, filtering and organizing data is a much more essential process than building the system's infrastructure."

🏷️ Tags & Hashtags

#ArtificialIntelligence #AI #MachineLearning #DeepLearning #LLM #LargeLanguageModel #PromptEngineering #AgentDesign #AI Agents #Ollama #ToolCalling #ReAct #SubAgent #Orchestrator #StructuredOutput #Rubric #FewShot #Grounding #Explainability #RAG #ROUGE #TokenCost #MuratKarakayaAkademi #AIEngineering #TechEducation #YouTubeEducation #Blogger

Are University Capstone Projects Still Necessary?

🎓 Are University Capstone Projects "Obsolete"? What Are We Really Grading?

🏛 In university engineering faculties, we are facing a staggering situation regarding "capstone projects"—often seen as the pinnacle of a student's educational life and where they are expected to put in serious effort for one or two semesters—that we can no longer ignore.

Engineering education, by its nature, aims to impart skills in problem-solving, analytical thinking, and designing a system from scratch. Traditionally, the capstone project is the ultimate test where a student puts all the theoretical knowledge acquired over 4 years into practice and proves they can stand on their own feet. I certainly exclude our students who focus on their projects ethically, with genuine hard work, turning night into day. However, the general landscape in the field and during jury defenses shows that we are frighteningly rapidly moving away from the core purpose of engineering education.

The issue has now moved far beyond simply copying ready-made code snippets from StackOverflow or GitHub. The process now includes the unchecked use of artificial intelligence tools in a way that "adds zero vision and skill to the student."

The Next-Generation Landscape Juries Face

When you sit down to evaluate a project, the anatomy of the work presented to you now looks very similar. We can group the flaws of this new era under three main headings:

🤖 Frankenstein Projects

When you open the hood and look inside projects that seem highly complicated and appear to use modern architectures from the outside or on the presentation screen, you encounter utter chaos. In reality, there is no "engineering design"; you see that many ready-made infrastructures are somehow "stitched together" using Large Language Models (LLMs) or API requests. There is no logical coherence between code blocks. Systems that fully meet no technical requirements (performance, security, scalability) and run almost by pure luck are brought before the jury as a "success."

📄 Candidates Alien to Their Own Reports

In the past, even if projects were incomplete, the student knew where they made a mistake in the code they wrote or the circuit they built. Today, however, when we ask students about the most fundamental components of their project or their engineering choices at critical decision points, they cannot explain them. Questions like "Why did you choose this algorithm?" or "How will this database architecture handle this load?" remain unanswered. The saddest part is realizing they haven't even read or understood the statements, numbers, and tables in the brilliantly academic-sounding report (written by AI) they claim to have "prepared themselves."

🛟 Passing the Buck in Defenses

An engineer is someone who puts their signature under their work and takes responsibility. Yet, the answers we get to our questions during the jury usually point to a "third party": "It wrote it like this", "It gave these results", "When I fed the data to the system, it generated this graph". We frequently and sadly see that AI has ceased to be a "tool" that accelerates the learning process and has become a "subcontractor" onto which all cognitive action and responsibility are dumped.

We could multiply these examples for pages with anecdotes from the field. Artificial intelligence will not leave our lives; on the contrary, it will become even more integrated. Rejecting this is nothing more than Luddism. However, there are crucial questions that academia and the industry need to ask themselves and urgently open up for discussion.

❓️ The Big Questions

1

Under these circumstances, how realistic and useful to them is it to still give students 2 semesters of time for projects that an AI assistant can prototype in a few hours, and to take the resulting code seriously and grade it at the end of these processes?

2

Can our traditional evaluation methods (reading reports, listening to slide presentations) truly measure the student's engineering reflexes, problem-solving skills, and ethical understanding in an age where AI "solves" and perfectly packages everything?

3

If the professors on the jury are also using another AI to read the reports, at the end of the day, are we grading the student's capacity or the outputs of the AI model (ChatGPT, Claude, etc.) they used?

4

So what is the solution? How should we update this system? How can we transition to evaluating students as individuals who "design and manage systems" rather than just "writing code"?

We must approach this problem not with outdated rules like "ban artificial intelligence," but by completely changing our evaluation metrics. Perhaps capstone projects should no longer be months-long coding assignments; they should transform into System Design interviews where the candidate defends an architecture by drawing it on a board live in front of the jury and explains how they used AI "correctly and ethically."

I am very curious about the observations, experiences, and most importantly, the proposed solutions of my esteemed colleagues in academia and the industry regarding this issue. How do you think we will get out of this situation? Let's meet in the comments! 👇

#MuratKarakayaAkademi #Engineering #ArtificialIntelligence #Academia #Education #CapstoneProject #HigherEducation #EngineeringEthics #FutureEngineers

Üniversitelerde Bitirme Projelerine İhtiyaç Kaldı Mı?

🎓 Üniversitelerde Bitirme Projelerine "İhtiyaç Kaldı Mı?" Gerçekten Neyi Puanlıyoruz?

🏛 Üniversitelerin mühendislik fakültelerinde, öğrencilerin eğitim hayatlarının zirvesi olarak görülen ve bir veya iki dönem boyunca ciddi bir emek vermesi beklenen "bitirme projelerinde" artık görmezden gelemeyeceğimiz, sarsıcı bir tabloyla karşı karşıyayız.

Mühendislik eğitimi, doğası gereği problem çözme, analitik düşünme ve sıfırdan bir sistem tasarlama yetilerini kazandırmayı hedefler. Geleneksel olarak bitirme projesi, öğrencinin 4 yıl boyunca edindiği tüm teorik bilgiyi pratiğe döktüğü, kendi ayakları üzerinde durduğunu kanıtladığı nihai bir sınavdır. Etiğiyle, alın teriyle projesine odaklanan, gecesini gündüzüne katan öğrencilerimizi elbette tenzih ediyorum. Ancak sahadaki ve jürilerdeki genel manzara, mühendislik eğitiminin temel amacından korkutucu bir hızla uzaklaştığımızı gösteriyor.

Artık mesele sadece StackOverflow'dan veya GitHub'dan hazır kod parçacıkları kopyalamanın çok ötesine geçti. Sürece, yapay zeka araçlarının "öğrenciye hiçbir vizyon ve beceri kazandırmayan" o denetimsiz kullanımı dahil oldu.

Jürilerin Karşılaştığı Yeni Nesil Manzara

Bir projeyi değerlendirmek için masaya oturduğunuzda, karşınıza gelen çalışmaların anatomisi artık birbirine çok benziyor. Bu yeni dönemin defolarını üç ana başlık altında toplayabiliriz:

🤖 Frankenstein Projeler

Dışarıdan veya sunum ekranından bakıldığında son derece komplike, modern mimariler kullanılmış gibi görünen projelerin kaputunu açıp içine girdiğinizde tam bir kaosla karşılaşıyorsunuz. Aslında ortada bir "mühendislik tasarımı" yok; birçok hazır altyapının, Büyük Dil Modelleri (LLM) veya API istekleriyle birbirine "bir şekilde" teyellendiğini görüyorsunuz. Kod blokları arasında mantıksal bir bütünlük yok. Hiçbir teknik gereksinimi (performans, güvenlik, ölçeklenebilirlik) tam karşılamayan ve adeta şans eseri çalışan sistemler jürinin önüne "başarı" olarak getiriliyor.

📄 Kendi Raporuna Yabancı Adaylar

Eskiden projeler eksik çalışsa bile, öğrenci yazdığı kodun veya kurduğu devrenin neresinde hata yaptığını bilirdi. Bugün ise öğrencilere projenin en temel bileşenlerini veya kritik karar noktalarındaki mühendislik tercihlerini sorduğumuzda izah edemiyorlar. "Neden bu algoritmayı seçtin?" veya "Bu veri tabanı mimarisi bu yüke nasıl dayanacak?" soruları cevapsız kalıyor. İşin en acı tarafı, "biz hazırladık" dedikleri, muazzam bir akademik dille (Yapay Zeka tarafından) yazılmış rapordaki ifadeleri, rakamları ve tabloları kendilerinin dahi okumadığını, anlamadığını fark ediyoruz.

🛟 Faili Meçhul Savunmalar

Mühendis, yaptığı işin altına imzasını atan ve sorumluluk alan kişidir. Oysa jüride sorduğumuz sorulara aldığımız cevaplar genellikle "üçüncü bir şahsı" işaret ediyor: "Böyle yazdı", "Bu sonuçları verdi", "Sisteme veriyi verince bu grafiği çıkarttı". Yapay zekanın, öğrenme sürecini hızlandıran bir "araç" olmaktan çıkıp, tüm düşünsel eylemin ve sorumluluğun yıkıldığı bir "taşeron" haline geldiğini sıklıkla ve üzülerek görüyoruz.

Bütün bu örnekleri, sahadan anektodlarla sayfalarca artırabiliriz. Yapay zeka hayatımızdan çıkmayacak, aksine daha da entegre olacak. Bunu reddetmek ludditlikten öteye gitmez. Ancak akademinin ve sektörün kendisine dönüp sorması gereken, acilen tartışmaya açmamız gereken can alıcı sorular var.

❓️ Çılgın Sorular

1

Tüm bu şartlar altında, bir yapay zeka asistanının birkaç saat içinde prototipini çıkarabileceği projeler için öğrencilere hala 2 dönem zaman vermek ve bu süreçlerin sonunda ortaya çıkan kodu ciddiye alıp puanlamak ne kadar gerçekçi ve onlara ne kadar faydalı?

2

Geleneksel değerlendirme yöntemlerimiz (rapor okuma, slayt sunumu dinleme), yapay zekanın her şeyi "çözdüğü" ve mükemmel ambalajladığı bu çağda, gerçekten öğrencinin mühendislik refleksini, problem çözme becerisini ve etik anlayışını ölçebiliyor mu?

3

Eğer jürideki hocalar da raporları okumak için başka bir yapay zeka kullanıyorsa, günün sonunda biz öğrencinin kapasitesini mi yoksa kullandığı yapay zeka modelinin (ChatGPT, Claude vb.) çıktılarını mı notluyoruz?

4

Peki çözüm ne? Bu sistemi nasıl güncellemeliyiz? Öğrencileri "kod yazan" değil, "sistem tasarlayan ve yöneten" bireyler olarak değerlendirmeye nasıl geçebiliriz?

Artık "Yapay zeka yasaklansın" gibi çağ dışı kurallarla değil, değerlendirme metriklerimizi tamamen değiştirerek bu soruna yaklaşmalıyız. Belki de bitirme projeleri artık aylar süren kodlama ödevleri değil; adayın canlı yayında jüri karşısında bir mimariyi tahtaya çizerek savunduğu, yapay zekayı nasıl "doğru ve etik" kullandığını anlattığı Sistem Tasarımı (System Design) mülakatlarına dönüşmeli.

Akademideki değerli hocalarımın ve sektördeki meslektaşlarımın bu konudaki gözlemlerini, yaşadıkları olayları ve en önemlisi çözüm önerilerini çok merak ediyorum. Sizce bu işin içinden nasıl çıkacağız? Yorumlarda buluşalım! 👇

#MuratKarakayaAkademi #Mühendislik #YapayZeka #Akademi #Eğitim #BitirmeProjesi #YüksekÖğretim #MühendislikEtiği #GeleceğinMühendisleri

Gemini Free Tier LLM APIs for Developers

Technical Review & Strategy

Gemini LLM Free Tier for Developers: Limits and Application Architecture

Published by: Murat Karakaya Akademi • May 2026 • Read Time: 8 min

The biggest hurdle in developing AI applications is the high cost of APIs. Google's updated Gemini Free Tier, as of May 2026, offers revolutionary opportunities for engineers looking to overcome this barrier.

For a modern AI engineer, it's not just about the "intelligence" of a model; it's also about the technical skill of working efficiently within its usage constraints (Rate Limits). In this guide, we will analyze the capacities of free models and how to manage the limits that challenge these capacities with technical precision.

1. Model Segmentation and Use Cases

Model Group	Core Feature	Ideal Use Case
Gemini 3.1 Flash Lite	Low Latency	Fast chat interfaces and simple automations.
Gemini 2.5 Flash	High Logic	Code generation and complex data analysis.
Gemma 4 (26B/31B)	Open Architecture	Sensitive data and long document processing.
Gemini Embedding 2	Vector Space	Semantic search and RAG systems.

2. Key Rate Limit Concepts: RPM, TPM, and RPD

• RPM (Requests Per Minute): The maximum number of calls you can make in a single minute.
• TPM (Tokens Per Minute): The total volume of input and output processed per minute.
• RPD (Requests Per Day): Your total daily usage quota.

3. Technical Parameters and Limit Analysis

Model Name	RPM	TPM	RPD
Gemini 3.1 Flash Lite	15	250K	500
Gemini 2.5 Flash	5	250K	20
Gemma 4 (All Versions)	15	Unlimited	1.5K
Gemini Embedding 2	100	30K	1K

💡 Strategic Recommendations for Architecture

Hybrid Model Usage: Gemini 2.5 Flash offers only 20 requests per day. Position this model as the "Chief Decision Maker" of your system. Delegate routine tasks like input validation or simple summarization to Flash Lite (500 RPD) to increase your daily capacity by 25 times.

The Gemma 4 Advantage: If your project involves analyzing massive text files, opting for the Gemma 4 series, which has no TPM limit, is the only way to avoid token overhead.

Conclusion: Limits Are Guides, Not Barriers

Building professional-grade pilot projects with free-tier models is entirely possible. With proper error handling and intelligent model selection, you can build a cost-effective AI infrastructure.

Learn API Integrations Through Practice

Learn how to manage Rate Limit errors at the code level and adapt them to real-world projects in our dedicated training series on the Murat Karakaya Akademi YouTube channel:

👉 Visit Channel: youtube.com/@MuratKarakayaAkademi

#MuratKarakayaAkademi #GeminiAI #LLM #Gemma4 #ArtificialIntelligence #MachineLearning #GoogleAI #RateLimits #AIEngineering #Python #FreeTier #GenerativeAI

Geliştiriciler İçin Gemini Ücretsiz (Free Tier) Dil Modelleri

Teknik İnceleme & Strateji

Geliştiriciler İçin Gemini Free Tier: Limitler ve Uygulama Mimarisi

Yayınlayan: Murat Karakaya Akademi • Mayıs 2026 • Okuma Süresi: 8 dk

Yapay zeka uygulamaları geliştirirken karşılaşılan en büyük engel, yüksek API maliyetleridir. Google'ın Mayıs 2026 itibarıyla güncellediği Gemini Ücretsiz Katmanı (Free Tier), bu bariyeri aşmak isteyen mühendisler için devrimsel olanaklar sunuyor.

Modern bir AI mühendisi için sadece modelin "zekası" değil, o modelin kullanım kısıtlamaları (Rate Limits) içinde nasıl verimli çalıştırılacağı da kritik bir beceridir. Bu rehberde, ücretsiz modellerin kapasitelerini ve bu kapasiteleri zorlayan limitlerin nasıl yönetileceğini teknik detaylarıyla inceliyoruz.

1. Model Segmentasyonu ve Kullanım Senaryoları

Model Grubu	Öne Çıkan Özellik	İdeal Kullanım Senaryosu
Gemini 3.1 Flash Lite	Düşük Gecikme	Hızlı chat arayüzleri ve basit otomasyonlar.
Gemini 2.5 Flash	Yüksek Mantık	Kod üretimi ve karmaşık veri analizi.
Gemma 4 (26B/31B)	Açık Mimari	Hassas veriler ve uzun döküman işleme.
Gemini Embedding 2	Vektör Uzayı	Semantik arama ve RAG sistemleri.

2. Rate Limit Kavramları: RPM, TPM ve RPD

• RPM (Requests Per Minute): Bir dakika içinde yapılabilecek maksimum çağrı sayısı.
• TPM (Tokens Per Minute): Dakikada işlenebilen toplam girdi ve çıktı hacmi.
• RPD (Requests Per Day): Günlük toplam kullanım hakkı.

3. Teknik Parametreler ve Limit Analizi

Model Name	RPM	TPM	RPD
Gemini 3.1 Flash Lite	15	250K	500
Gemini 2.5 Flash	5	250K	20
Gemma 4 (Tüm Versiyonlar)	15	Sınırsız	1.5K
Gemini Embedding 2	100	30K	1K

💡 Uygulama Mimarisi İçin Stratejik Öneriler

Hibrit Model Kullanımı: Gemini 2.5 Flash günlük sadece 20 istek sunar. Bu modeli sistemin "ana karar vericisi" yapın. Girdi doğrulama ve basit özetleme gibi işleri 500 RPD sunan Flash Lite modeline devrederek günlük kapasitenizi 25 kat artırabilirsiniz.

Gemma 4 Avantajı: Eğer projeniz devasa metinleri analiz ediyorsa, TPM sınırı olmayan Gemma 4 serisini tercih etmek, token maliyetinden kaçınmanın tek yoludur.

Sonuç: Limitler Engel Değil, Kılavuzdur

Ücretsiz katman modelleriyle profesyonel seviyede pilot projeler üretmek tamamen mümkündür. Doğru hata yönetimi ve akıllı model seçimi ile maliyetsiz bir AI altyapısı kurabilirsiniz.

API Entegrasyonlarını Uygulamalı Öğrenin

Rate Limit hatalarının kod seviyesinde nasıl yönetildiğini ve gerçek dünya projelerine nasıl uyarlandığını Murat Karakaya Akademi YouTube kanalımızdaki özel eğitim serisinde bulabilirsiniz:

👉 Kanalı Ziyaret Et: youtube.com/@MuratKarakayaAkademi

#MuratKarakayaAkademi #GeminiAI #LLM #Gemma4 #YapayZeka #MachineLearning #GoogleAI #RateLimits #AIEngineering #Python #FreeTier #GenerativeAI

Ollama Cloud ile Açık Kaynak Büyük Dil Modellerini (LLM) Bulutta Kullanmak

Ollama Cloud ile Açık Kaynak LLM'leri İndirmeden Denemek

Açık Kaynak büyük dil modelleri (LLM) dünyasında her gün yeni bir model ve yeni bir sürüm konuşuluyor. Bu çok iyi bir haber, çünkü artık "tek bir model"e mahkum değiliz. Ama pratikte çoğu kişi aynı iki probleme takılıyor: (1) Büyük modeller yerel GPU VRAM'ine sığmıyor, (2) Birden fazla modeli denemek için her seferinde devasa dosyalar indirmek, kurmak, silmek hem zaman hem de disk alanı tüketiyor. Kısacası, öğrenme ve deneme süreci daha en başta yorucu hale gelebiliyor.

Ben bu eğitimi tam da bu yüzden hazırladım: Açık Kaynak LLM'leri Bilgisayarınıza model dosyalarını indirip biriktirmeden de test edebilin. Üstelik sadece "çalıştırma" değil, doğru model seçimi ve uygulamaya entegrasyon mantığını da anlayın. Bu yazı, YouTube'daki eğitimimin blog formatında, ders notu kadar derinlemesine hazırlanmış versiyonu. Adım adım giderken, neden-sonuç ilişkisini de kurmaya çalışacağım.

Eğitim videosu (YouTube canlı yayın kaydı): https://youtube.com/live/QEZ8oF4A68k

Kodlar ve dokümanlar (GitHub deposu): https://github.com/kmkarakaya/OllamaCloud

Not: Bu yazıda mümkün oldukça Türkçe terimler kullanıyorum. Örneğin "Açık Kaynak" (open source), "bulut", "belirteç" (token), "akış" (stream) gibi. Kod ve komutlarda ise resmi isimler ve parametreler aynen kalıyor.

Bu Ders Notunu Nasıl Kullanmalısın?

Bu yazı iki tip okuyucu için tasarlandı:

• LLM dünyasına yeni girenler: "Ben nereden başlayacağım, hangi kavramlar önemli?" diyenler.
• Uygulama geliştirmek isteyenler: "Ben Python ile bir şey kurmak istiyorum, model denemeyi hızlı hale getirmek istiyorum." diyenler.

Benim önerim şu: Önce kavramları ve karar mantığını oku. Sonra CLI ile bir modeli çalıştır. Ardından API ve Python bölümüne geç. En sonda repodaki iki örneği (model karşılaştırma betiği ve Streamlit demo) çalıştırıp sonuçları yorumla. Bu sırayla ilerlersen, "ne yaptığını bilerek" ilerlemiş olursun.

Temel Kavramlar: Modeller Neden Ağır? (VRAM, RAM, Disk, belirteç)

Bir modelin "büyük" veya "ağır" olması tek bir şeye bağlı değil. Yeni başlayanların kafasını en çok karıştıran nokta da bu. Ben burada üç kaynak üzerinden anlatıyorum: Disk, RAM ve VRAM.

• Disk: Model dosyalarını indirip sakladığın yer. Birkaç model denemek bile onlarca GB yapabilir.
• RAM: CPU belleği. Bazı durumlarda (özellikle CPU ile çalışan senaryolarda) RAM sınırlayıcı olur.
• VRAM: GPU belleği. Büyük modellerin yerelde hızlı çalışmasında çoğu zaman asıl sınırlayıcı kaynak budur.

Parametre sayısı arttıkça (örneğin 20B, 120B gibi) modelin kapasitesi artabilir, ama kaynak ihtiyacı da artar. Ancak tek mesele parametre sayısı değildir. Model çalışırken "KV cache" (kısaca bağlam belleği) de büyür. Bu cache, konuşma uzadıkça ve context window büyüdükçe artar. Bu yüzden "kısa bir soru" ile "uzun bir sohbet" aynı modelde farklı kaynak tüketimi üretebilir.

Bir diğer kritik kavram: belirteç. Modelin okuduğu ve ürettiği metin parçaları belirteçlere bölünür. Bir prompt ne kadar uzunsa, o kadar fazla belirteç işlenir. Bir konuşma geçmişi ne kadar uzunsa, modelin "tek seferde düşünmesi" için o kadar fazla belirteç taşınır. Bu hem süreyi (gecikme) hem de bellek ihtiyacını etkiler. Bu yüzden iyi bir pratik: Modeli değerlendirirken sadece tek bir prompt değil, farklı uzunluklarda promptlar denemek.

Peki quantization (kuantizasyon) ne işe yarar? Çok basit anlatayım: Modeli daha düşük hassasiyetle temsil ederek daha az bellek kullanmasını sağlar. Bu sayede bazı modeller yerelde çalışabilir hale gelir. Ama bazen kalite ve tutarlılık üzerinde etkisi olabilir. Bu nedenle model seçimi yaparken "en büyük model en iyisidir" gibi basit bir kural yok. Senin senaryon için "yeterince iyi + yeterince hızlı + yönetilebilir maliyet" dengesi önemlidir.

Bu noktada Ollama Cloud'un değeri ortaya çıkıyor: İndirme ve donanım bariyerini azaltıp, senin hızlıca öğrenme ve deneme yapmanı sağlıyor. Yani önce doğru modeli seçiyorsun, sonra yerel veya bulut stratejini buna göre planlıyorsun.

KV Cache ve Context Window: Uzun Sohbet Neden Yavaşlar?

Yeni başlayanların en sık yaşadığı sürprizlerden biri şudur: Aynı model, kısa bir promptta çok hızlı cevap verirken; konuşma uzadıkça veya tek prompt çok uzayınca bariz şekilde yavaşlar. Bunun temel nedeni "modelin geçmişi nasıl taşıdığı" ile ilgilidir. Dil modelleri, her yeni belirteç üretirken önceki belirteçlere dikkat (attention) mekanizmasıyla bakar. Konuşma uzadıkça bakması gereken içerik artar; bu da hesaplama maliyetini ve bellek ihtiyacını yükseltir.

Bu işin bellek tarafındaki adı çoğu yerde KV cache olarak geçer. Çok basit anlatımla: Model, önceki belirteçlere ait bazı ara temsil bilgilerini (key/value) cache'ler ve sonraki adımlarda bunları kullanır. Context window büyüdükçe bu cache de büyür. Yerelde GPU kullanıyorsan bu cache çoğu zaman VRAM'de tutulur ve VRAM'in sınırlıysa uzun konuşmalarda daha çabuk sınıra dayanırsın. bulut'da bu sınır sende görünmez ama performans etkisini yine hissedebilirsin.

Bu yüzden ben model denemesinde şunu özellikle öneriyorum: Sadece "tek cümlelik bir soru" ile karar verme. Aynı modelde kısa prompt, orta prompt ve uzun prompt dene. Bir de "konuşma geçmişi" senaryosu dene. Çünkü gerçek uygulamada çoğu zaman kullanıcı bir soru sorup çıkmıyor; takip sorusu soruyor, detay istiyor, format değiştiriyor. Modelin bu akıştaki davranışı, tek seferlik cevap kadar önemlidir.

Pratik bir performans ipucu: Uygulamada konuşma geçmişini sınırsız büyütme. Gerekirse eski mesajları özetle, kritik noktaları "memory" gibi tek bir mesajda taşı. RAG (retrieval-augmented generation) gibi teknikler de burada devreye girer: Her şeyi konuşma geçmişinde tutmak yerine, ilgili bilgiyi dışarıdan çekip prompta eklersin. Bu hem maliyeti hem de gecikmeyi yönetmeyi kolaylaştırır.

Ollama Cloud Nedir? (CLI ve API İki Yol)

Ollama Cloud, desteklenen modelleri bulut üzerinden çalıştırıp denemeni sağlayan bir altyapı. Senin tarafında iki "arayüz" var: Ollama CLI ve Ollama API. Benim ders notu yaklaşımımda bunlar iki farklı hedefe hizmet eder:

• CLI yolu: Hızlı deneme ve hızlı kıyaslama. Prompt yaz, cevap al, model davranışını gör.
• API yolu: Uygulama entegrasyonu. Python ile web app, bot, servis veya otomasyon kur.

Resmi dokümanlar (okurken açık dursun): https://docs.ollama.com/cloud, https://docs.ollama.com/api

Not: "Ücretsiz deneme" ve limitler dönemsel olarak değişebilir. En güncel bilgiyi resmi sayfalardan kontrol etmeni öneririm.

Ne Zaman bulut, Ne Zaman Yerel?

bulut ve yerel kullanım birbirinin alternatifi değil; çoğu zaman birbirini tamamlar. Ben pratikte şöyle karar veriyorum:

• bulut-öncelikli: Model denemek, model seçmek, hızlı prototip yapmak, eğitim/demo üretmek.
• Local-first: Offline çalışma, çok sık istek, veri politikası nedeniyle tamamen yerel zorunluluk.

Eğer amacın "hangi model işimi görür?" sorusunu cevaplamaksa bulut yaklaşımı büyük hız kazandırır. Modeli seçtikten sonra yerelde koşmak istiyorsan, o aşamada donanım yatırımı veya daha küçük/kuantize bir model seçimi mantıklı hale gelir. Yani benim için bulut çoğu zaman bir "hızlandırıcı katman".

Model Deneme ve Karşılaştırma İçin Basit Bir Rubrik

Model denemek demek, aynı soruyu üç modele sormak demek değildir. Gerçek bir karşılaştırma yapmak için küçük bir rubrik gerekir. Benim kullandığım basit rubrik şu başlıklardan oluşur:

• Talimat takibi: "Şu formatta yaz" dediğimde uyuyor mu?
• Tutarlılık: Aynı soruyu tekrar sorunca benzer kalite veriyor mu?
• Yapı ve okunabilirlik: Cevap düzenli mi, maddeleme iyi mi?
• Doğruluk: Bariz hatalar yapıyor mu, uydurma eğilimi var mı?
• Hız: Aynı prompt için yanıt süresi kabul edilebilir mi?
• Dil uyumu: Türkçe sorularda Türkçe kalitesi yeterli mi?

Bu rubriği kullanarak "model seçimi"ni hızlandırabilirsin. Örneğin eğitimde kullandığım yaklaşım: Aynı konuda 2-3 farklı prompt tipi hazırla, sonra her modeli bu prompt setiyle test et. Böylece tek bir cevaba göre karar vermezsin. Özellikle "format zorlayan" promptlar modelin talimat takibini çok net gösterir.

Bu rubriği repodaki compare_models.py ile otomatikleştirmeye başladık. betik mükemmel bir kıyaslama değil, ama doğru düşünme biçimini öğretir: Önce yapılandırılmış görevler, sonra gerçek çıktı incelemesi.

Prompt Tasarımı İpuçları: Modeli Doğru Sınamak

Bir modelin "iyi" veya "kötü" olduğuna karar vermek için önce doğru prompt yazmak gerekir. Çünkü LLM'ler, soruyu nasıl sorduğuna göre çok farklı davranabilir. Benim ders notu şeklinde önerdiğim basit yaklaşım: Promptu dört parçaya böl ve her parçayı net yaz.

• Rol: Modelden nasıl davranmasını istiyorsun? (Örn: "Bir eğitmen gibi anlat.")
• Hedef: Tam olarak ne istiyorsun? (Örn: "RAG'i 5 maddeyle açıkla.")
• Kısıt: Uzunluk, dil, format, ton gibi sınırlar. (Örn: "Her madde 1 cümle olsun.")
• Çıktı formatı: Madde madde mi, JSON mu, tablo mu? (Örn: "Başlık + maddeler.")

Karşılaştırma yaparken de aynı konsept geçerli: Aynı rubrikle ölçmek istiyorsan, modellerin hepsine aynı formatı zorlayan promptları ver. Örneğin Türkçe üreteceksen mutlaka Türkçe prompt seti hazırla. Kod yazdıracaksan "basit kod", "hata ayıklama", "refactor" gibi farklı kod görevleri ekle. Bu sayede tek bir promptta parlayan ama diğer görevlerde dağılan modelleri erken fark edersin.

Bir başka pratik ipucu: Deneme promptlarını "gerçek iş" promptlarından ayır. Deneme promptu daha kısa ve daha kontrollü olur; gerçek iş promptu ise daha karmaşık ve daha çok bağlam içerir. Bu yüzden karar verirken iki tür promptu da kullan. Deneme promptu ile ele, gerçek iş promptu ile doğrula.

Güvenlik ve İyi Pratikler: API Key ile Çalışmak

API key bir şifre gibi düşünülmeli. En sık yapılan hata, API key'i koda gömmek veya depo içinde paylaşmak. Benim önerim: API key'i bir ortam değişkeni olarak tanımla ve uygulamada oradan oku.

Resmi yetkilendirme dokümanı: https://docs.ollama.com/api/authentication

Windows PowerShell tarafında, geçerli oturum için örnek:

$env:OLLAMA_API_KEY = "your_api_key_here"

Bu şekilde key'i kaynak koduna yazmadan, hem CLI tarafında hem de Python tarafında kullanabilirsin. Eğitim içeriklerinde özellikle şunu vurguluyorum: Key yönetimi "küçük bir detay" değil; ileride üretim ortamına gittiğinde en kritik alışkanlıklardan biri olacak.

CLI ile Başlamak: İlk Deneme Akışı (Neden Bu Komutlar?)

Önce Ollama'nın Windows kurulumu gerekiyor. Resmi Windows kurulum sayfası: https://docs.ollama.com/windows

Kurulumdan sonra amaç şu: bulut tarafına giriş yap ve bir modeli terminalde çalıştır. Temel akış:

ollama --version
ollama signin
ollama run gpt-oss:120b-cloud

Burada ollama signin kritik. bulut erişimi gerektiren işlemlerde yerel CLI'nin kimlik doğrulamasını yapmış oluyorsun. Sonra ollama run ile modeli interaktif moda alıyorsun. Bu noktada önemli pratik: İlk denemelerde kısa promptlarla başla, sonra uzun promptlara geç. Çünkü uzun prompt, hem hız hem de bağlam yönetimi açısından modeli daha fazla zorlar.

Bir diğer önemli not: bulut model isimleri CLI tarafında bazen -cloud ekiyle gelir. API tarafında ise model adları farklı görünebilir. Bu yüzden ben API entegrasyonlarında "model adını hardcode etme" alışkanlığını bırakmanı öneriyorum. Bunun çözümü bir sonraki bölümde: /api/tags.

Direkt API Yolu: /api/tags ile Model Keşfi, /api/sohbet ile Cevap

Uygulama geliştireceksen API tarafı kritik. Ben burada iki endpointi "temel taş" gibi görüyorum:

• /api/tags: Hangi modeller erişilebilir? Bu sorunun cevabı.
• /api/sohbet: Mesaj gönderip cevap almak.

Endpoint dokümanları: https://docs.ollama.com/api/tags, https://docs.ollama.com/api/chat

Benim pratik yaklaşımım: Model adını "varsayma". Önce /api/tags ile listeyi çek, sonra uygulamanda o listeden seçim yaptır. Bu sayede bir model erişilebilir değilse uygulama kırılmaz; sadece seçeneklerde görünmez.

Minimal bir curl örneği (PowerShell'de):

curl __URL_16__ `
  -H "Authorization: Bearer $env:OLLAMA_API_KEY"

sohbet tarafında stream parametresi önemli bir kavram. stream=false dersen tek seferde cevap alırsın. stream=true dersen cevap parça parça gelir. Web uygulamalarında akış kullanıcı deneyimini iyileştirir, ama kodu biraz daha dikkatli yazmayı gerektirir. Eğitimde ben önce stream=false ile mantığı kurup, sonra akışa geçmeni öneriyorum.

Python ile Entegrasyon: Mantığı Bir Kez Kur, Her Yerde Kullan

Python tarafında benim önerim şu: Önce en küçük "çalışıyor mu?" prototipini kur. Sonra aynı mantığı web uygulamasına taşı. Ollama Cloud Python dokümanı burada: https://docs.ollama.com/cloud#python

Kullandığımız Python paketi: https://github.com/ollama/ollama-python

Python tarafında temel fikir:

• İstemciyi host="__URL_21__" ile bulut'a yönlendir
• Header'a Authorization: Bearer ... koy
• chat() çağrısında model ve mesajları gönder

Minimal örnek:

import os
from ollama import Client

client = Client(
    host="__URL_22__",
    headers={"Authorization": f"Bearer {os.environ['OLLAMA_API_KEY']}"},
)

resp = client.chat(
    model="gpt-oss:120b",
    messages=[{"role": "user", "content": "RAG nedir? 5 maddeyle anlat."}],
    stream=False,
)

print(resp["message"]["content"])

Burada mesaj formatı çok önemli. Mesajlar bir liste ve her mesajın role alanı var (örneğin user). Gerçek uygulamada konuşma geçmişi tutarsın: Önceki mesajları da yeni promptla birlikte gönderirsin. Bu sayede model bağlamı "hatırlar". Ama şu riski unutma: Konuşma geçmişi uzadıkça belirteç sayısı artar; bu da gecikmeyi artırabilir. Bu yüzden pratik bir yöntem: Geçmişi sınırlamak veya kritik noktaları özetleyip "memory" gibi göndermek.

Hata senaryolarını ders notu gibi düşünelim:

• 401 Unauthorized: API key yanlış veya header formatı hatalı. İlk kontrol: ortam değişkeni + auth dokümanı.
• 404 / model not found: Model adı erişilebilir değil; önce /api/tags ile listeyi kontrol et.
• Timeout/slow: Çok büyük model veya yoğunluk; daha küçük modelle dene, istekleri azalt, akış kullan.

Bu üç hata tipi, pratikte en sık görülenler. Eğitimde de özellikle "önce tags, sonra sohbet" mantığını vurguluyorum.

depo Walkthrough: İki Bağımsız Örnekle Öğrenmeyi Hızlandırmak

Eğitimi izleyip "tamam anladım" demek kolay. Asıl değer, iki örneği çalıştırıp sonuçları yorumlamakta. depo içinde üç kritik dosya var: requirements.txt, compare_models.py, app.py. Bu üçü birlikte "deneme -> karşılaştırma -> demo" akışını tamamlıyor.

Önce bağımlılıkları kurmak ve örnekleri çalıştırmak için pratik komutlar:

pip install -r requirements.txt
python compare_models.py
streamlit run app.py

Şimdi iki örneği tek tek ders notu gibi inceleyelim.

compare_models.py ne yapıyor? Bu betik "model seçimi" problemine pratik bir yaklaşım getiriyor. İçindeki iki yapı çok önemli:

• MODELS: Karşılaştırılacak model listesi (ör. gpt-oss:20b, gpt-oss:120b, qwen3-coder:480b)
• TASKS: Modelin cevap vermesini istediğin yapılandırılmış görevler

Scriptin yaklaşımı şu: Her modele aynı görevleri sorar, yanıt süresini ölçer ve basit bir kalite skoru çıkarır. Bu skor bir hakem değil; bir "erken sinyal". Skorun mantığı dosyada açık:

• Anahtar kelime kapsama skoru (0-60): Görev için kritik kelimeleri geçiriyor mu?
• Format skoru (0-40): Maddeleme var mı, satır sayısı makul mü, yanıt uzunluğu yeterli mi?

Skorun amacı şu: Hızlıca "bu model talimatları takip ediyor mu?" sorusuna yaklaşmak. Ama karar verirken mutlaka raporu okuyacaksın. betik, tüm çıktıları model_comparison_report.md dosyasına yazar. Bu dosyayı açıp yanıtları yan yana okumak, gerçek kalite farkını görmenin en iyi yoludur.

Bu betiği kendi senaryona uyarlamak için pratik öneriler:

• Kendi işine uygun 3-5 görev ekle (Türkçe özetleme, kod üretimi, e-posta yazma, hata ayıklama vb.).
• MODELS listesini /api/tags ile gördüğün erişilebilir modellere göre güncelle.
• Skorun "tek ölçüt" olmadığını unutma; raporu mutlaka oku.

Şimdi ikinci örnek: app.py. Bu dosya Streamlit ile basit bir web arayüzü kuruyor. Bu demo, özellikle öğrenme ve manuel test için çok değerli. Çünkü CLI'de hızlı denersin ama bazen promptları düzenlemek, farklı formatları denemek, çıktıyı kopyalayıp incelemek tarayıcıda daha rahattır.

Uygulamanın akışı:

• API key'i ortamdan alır veya kullanıcıdan ister.
• bulut'dan model listesini çeker ve seçim sunar.
• Prompt gönderilir, cevap ekranda gösterilir.

Bu yapının asıl öğretici tarafı şudur: Modeli "hardcode" etmek yerine listeden seçtirmek. Böylece erişilebilir modeller değişse bile uygulama dayanıklı olur. Bu, üretim sistemlerinde de çok işe yarayan bir alışkanlıktır.

Uygulamayı geliştirmek istersen, başlangıç için birkaç fikir:

• Konuşma geçmişi (sohbet geçmişi) ekle: Önceki mesajları saklayıp tekrar gönder.
• akış yanıt ekle: Cevap yazılıyor gibi görünsün.
• Prompt şablonları ekle: "özetle / maddele / kod yaz" gibi hazır butonlar.
• Çıktıyı kaydet: Prompt ve cevapları logla, sonra analiz et.

Sık Yapılan Hatalar ve Pratik Çözümler

Bu bölüm gerçek hayatın özeti: Hata alırsın ve çözersin. Ben en sık şunları görüyorum:

• 401 Unauthorized: API key yok, yanlış veya header formatı hatalı. Önce Authentication dokümanına bak, sonra ortam değişkenini kontrol et.
• Model bulunamadı: Model adı erişilebilir değil. İlk adım: /api/tags ile modelleri listele ve doğru adı seç.
• Çok yavaş yanıt: Büyük model veya yoğunluk olabilir. Daha küçük model dene, promptu kısalt, akış kullanmayı düşün.
• Virtualenv karışıklığı: Farklı Python ortamına kurulum yapılıyor. En temiz yöntem: venv aç, sonra pip install -r requirements.txt.
• Türkçe karakterler bozuk görünüyor: Kopyalama yaparken HTML editör modu dışında yapıştırmış olabilirsin. Blogger'da HTML görünümünde yapıştırmak genelde en sorunsuz yoldur.

Bu hataların ortak mesajı şu: Önce bağlantı ve yetkiyi doğrula, sonra model listesini doğrula, en son uygulama kodunu kurcala. Bu sırayla ilerlemek zamandan tasarruf ettirir.

Sık Sorulan Sorular (SSS)

Bu eğitimden sonra en çok gelen soruları kısa ve net cevaplayayım. Buradaki amaç "ezber" değil; doğru kontrol noktalarını öğretmek.

• Ollama Cloud ücretsiz mi? Çoğu kişi bulutu "hızlı deneme" için kullanıyor. Ancak limit/politikalar zaman içinde değişebilir. En güncel bilgi için bulut sayfasını kontrol et.
• Hangi modeller var, hangisini seçmeliyim? "Şu model kesin var" diye varsayma. Önce /api/tags ile listeyi gör. Seçimi rubrikle yap: talimat takibi, tutarlılık, hız, Türkçe kalitesi ve senin senaryona uygunluk.
• CLI'de -bulut var ama API'de yok, neden? CLI ve API tarafında isimlendirme farklı görünebilir. Uygulama tarafında modeli listeden seçtirmen bu sorunu pratikte çözer.
• ollama signin ile API key aynı şey mi? Hayır. ollama signin daha çok CLI akışı için oturum açma mantığıdır. API tarafında ise genelde API key + Bearer header ile çalışırsın. Detay için Authentication sayfasına bak.
• Veri gizliliği açısından neye dikkat etmeliyim? Kural basit: Hassas veriyi göndermeden önce mutlaka politika/şartları oku ve kurumunun kurallarına göre hareket et. Eğitim ve demo sırasında gerçek müşteri verisi yerine sentetik/anonim veri kullanmak iyi bir alışkanlıktır.
• Türkçe karakterler bozuk görünürse? Genelde iki sebep olur: dosya encoding'i veya Blogger'a yapıştırma modu. Bu dosya UTF-8 olarak hazırlanmıştır. Blogger'da HTML modunda yapıştırmak çoğu zaman sorunu çözer.

Mini Çalışma: Kendi Deneme Setini Oluştur

Bu yazıyı gerçekten değerli kılmak için sana küçük bir "ödev" seti bırakmak istiyorum. Eğer bir modeli seçmek istiyorsan, şu üç tip prompt hazırla:

• Format testi: "5 maddeyle anlat, her madde 1 cümle olsun" gibi.
• Akıl yürütme testi: "Adım adım açıkla" gibi.
• Senaryo testi: "Benim işim şu, bana bir taslak çıkar" gibi.

Sonra aynı üç promptu üç farklı modelde dene. Karşılaştırma yaparken sadece "doğru mu?" diye bakma; rubriğe geri dön: Talimat takibi, tutarlılık, okunabilirlik ve hız. Bu küçük alışkanlık, öğrenme sürecini hızlandırır ve model seçimini daha sağlam yapar.

Benim Önerdiğim Deneme Stratejisi

Eğer bir proje için model seçeceksem ben genelde şu akışla ilerliyorum:

• Önce 2-3 aday model belirlerim (biri hızlı/küçük, biri büyük/kaliteli, biri kod odaklı vb.).
• compare_models.py ile hızlı karşılaştırma yaparım.
• Rapor dosyasından cevapları okur, talimat takibi ve tutarlılığa bakarım.
• Seçtiğim 1-2 modeli app.py ile manuel prompt testine sokarım.
• Sonra uygulama entegrasyonuna geçerim (Python client ile).

Bu akışın güzelliği şu: Model seçimi "hissiyat" değil, kısa ama sistematik bir deneme sürecine dayanıyor. Üstelik bunu donanım yatırımı yapmadan başlatabiliyorsun.

Videoyu ve Kodları Burada Bulabilirsin

YouTube eğitim kaydı: https://youtube.com/live/QEZ8oF4A68k

GitHub deposu (README ve örnek kodlar): https://github.com/kmkarakaya/OllamaCloud

Resmi kaynaklar:

• Ollama Cloud
• Ollama Cloud Python
• Ollama Windows
• Ollama API
• API Authentication
• API /tags
• API /sohbet
• ollama-python

Kapanış

Ben bu eğitimi, "donanımım yetmiyor" bahanesinin seni açık kaynak LLM denemekten uzaklaştırmaması için hazırladım. Ollama Cloud ile hem farklı modelleri hızlıca deneyebilir, hem de seçtiğin modeli Python tarafında gerçek bir uygulamaya bağlayabilirsin.

Eğer sen de açık kaynak LLM'leri hızlıca denemek, karşılaştırma yapmak ve pratik bir akış kurmak istiyorsan videoyu izle, depo içindeki örnekleri çalıştır, sonra kendi senaryona uyarlayıp geliştirmeye başla. Benzer içerikler için Murat Karakaya Akademi'yi takip etmeyi unutma.