Welcome to Barry's Blog!

这里记录着我的学习之路

Python SQLAlchemy与Alembic数据库迁移笔记

2026-03-30

技术

Python SQLAlchemy与Alembic数据库迁移

前言

SQLAlchemy 是 Python 中最流行的 ORM 框架之一，提供了完整的 SQL 能力和企业级持久化模式。Alembic 是 SQLAlchemy 作者开发的数据库迁移工具，轻量级且功能强大，类似于 Django 的 migration 或 Ruby on Rails 的 migrations。

一、SQLAlchemy 基础

1.1 安装

pip install sqlalchemy
# 或安装带异步支持的版本
pip install sqlalchemy[asyncio]

1.2 连接数据库

from sqlalchemy import create_engine

# SQLite
engine = create_engine('sqlite:///example.db')

# MySQL
engine = create_engine('mysql+pymysql://user:password@localhost:3306/dbname')

# PostgreSQL
engine = create_engine('postgresql://user:password@localhost:5432/dbname')

# 连接池配置
engine = create_engine(
    'mysql+pymysql://user:password@localhost:3306/dbname',
    pool_size=10,          # 连接池大小
    max_overflow=5,        # 超过pool_size后允许的最大连接数
    pool_timeout=30,       # 获取连接超时时间
    pool_recycle=3600,     # 连接回收时间
    echo=True              # 打印SQL日志
)

1.3 定义模型

from sqlalchemy import Column, Integer, String, DateTime, Text, ForeignKey
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import relationship
from datetime import datetime

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    
    id = Column(Integer, primary_key=True, autoincrement=True)
    username = Column(String(50), unique=True, nullable=False, comment='用户名')
    email = Column(String(100), unique=True, nullable=False, comment='邮箱')
    password_hash = Column(String(255), nullable=False)
    created_at = Column(DateTime, default=datetime.now, comment='创建时间')
    updated_at = Column(DateTime, default=datetime.now, onupdate=datetime.now, comment='更新时间')
    
    # 关联关系
    posts = relationship('Post', back_populates='author')
    
    def __repr__(self):
        return f"<User(id={self.id}, username='{self.username}')>"

class Post(Base):
    __tablename__ = 'posts'
    
    id = Column(Integer, primary_key=True)
    title = Column(String(200), nullable=False)
    content = Column(Text)
    user_id = Column(Integer, ForeignKey('users.id'), nullable=False)
    created_at = Column(DateTime, default=datetime.now)
    
    # 关联关系
    author = relationship('User', back_populates='posts')

1.4 Session 操作

from sqlalchemy.orm import sessionmaker, Session

# 创建Session工厂
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)

# 使用上下文管理器
from contextlib import contextmanager

@contextmanager
def get_db():
    db = SessionLocal()
    try:
        yield db
        db.commit()
    except Exception as e:
        db.rollback()
        raise e
    finally:
        db.close()

# CRUD 操作示例
def create_user(db: Session, username: str, email: str, password: str):
    user = User(username=username, email=email, password_hash=password)
    db.add(user)
    db.commit()
    db.refresh(user)
    return user

def get_user_by_id(db: Session, user_id: int):
    return db.query(User).filter(User.id == user_id).first()

def get_users(db: Session, skip: int = 0, limit: int = 100):
    return db.query(User).offset(skip).limit(limit).all()

def update_user(db: Session, user_id: int, **kwargs):
    user = db.query(User).filter(User.id == user_id).first()
    if user:
        for key, value in kwargs.items():
            setattr(user, key, value)
        db.commit()
        db.refresh(user)
    return user

def delete_user(db: Session, user_id: int):
    user = db.query(User).filter(User.id == user_id).first()
    if user:
        db.delete(user)
        db.commit()
    return user

1.5 查询进阶

from sqlalchemy import or_, and_, func, desc

# 条件查询
users = db.query(User).filter(User.username.like('%test%')).all()

# 多条件组合
users = db.query(User).filter(
    and_(
        User.username.like('%test%'),
        or_(User.email.endswith('@gmail.com'), User.email.endswith('@qq.com'))
    )
).all()

# 排序和分页
users = db.query(User).order_by(desc(User.created_at)).offset(10).limit(10).all()

# 聚合查询
from sqlalchemy import func
result = db.query(
    User.username,
    func.count(Post.id).label('post_count')
).join(Post).group_by(User.id).all()

# 关联查询（JOIN）
posts = db.query(Post).join(User).filter(User.username == 'admin').all()

# 使用 outerjoin
posts = db.query(Post).outerjoin(User).all()

# 子查询
subq = db.query(Post.user_id, func.count('*').label('count')).group_by(Post.user_id).subquery()
result = db.query(User, subq.c.count).outerjoin(subq, User.id == subq.c.user_id).all()

二、Alembic 数据库迁移

2.1 安装与初始化

pip install alembic

# 在项目根目录初始化
cd your_project
alembic init alembic

初始化后会生成以下结构：

your_project/
├── alembic/
│   ├── versions/          # 迁移脚本存放目录
│   ├── env.py            # Alembic 环境配置
│   ├── script.py.mako    # 迁移脚本模板
│   └── README
├── alembic.ini           # Alembic 配置文件
└── your_models.py

2.2 配置 alembic.ini

修改 alembic.ini 文件中的数据库连接：

# alembic.ini
[alembic]
# 迁移脚本存放目录
script_location = alembic

# 数据库连接字符串
sqlalchemy.url = mysql+pymysql://user:password@localhost:3306/dbname

# 也可以使用环境变量
# sqlalchemy.url = driver://user:pass@localhost/dbname

[post_write_hooks]
# 迁移脚本生成后执行的钩子（如格式化代码）
# hooks = black
# black.type = console_scripts
# black.entrypoint = black
# black.options = -q

2.3 配置 env.py

修改 alembic/env.py，导入你的模型：

# alembic/env.py
from logging.config import fileConfig

from sqlalchemy import engine_from_config
from sqlalchemy import pool

from alembic import context

# 导入你的 Base 和模型
import sys
sys.path.insert(0, '.')
from models import Base  # 替换为你的模型路径

# this is the Alembic Config object
config = context.config

# 设置 target_metadata 为你的 Base.metadata
target_metadata = Base.metadata

# 其他配置保持不变...

2.4 常用迁移命令

# 生成迁移脚本（自动检测模型变化）
alembic revision --autogenerate -m "initial tables"

# 手动创建空白迁移脚本
alembic revision -m "add user table"

# 查看当前数据库版本
alembic current

# 查看迁移历史
alembic history

# 升级到最新版本
alembic upgrade head

# 升级到指定版本
alembic upgrade <revision_id>

# 降级一个版本
alembic downgrade -1

# 降级到指定版本
alembic downgrade <revision_id>

# 降级到初始状态
alembic downgrade base

# 查看将要执行的SQL（不实际执行）
alembic upgrade head --sql

# 标记当前版本（不执行迁移）
alembic stamp head

2.5 迁移脚本示例

自动生成的迁移脚本示例：

# alembic/versions/123456789abc_initial_tables.py
"""initial tables

Revision ID: 123456789abc
Revises: 
Create Date: 2024-01-01 10:00:00.000000

"""
from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision = '123456789abc'
down_revision = None
branch_labels = None
depends_on = None


def upgrade():
    # 创建 users 表
    op.create_table(
        'users',
        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
        sa.Column('username', sa.String(length=50), nullable=False),
        sa.Column('email', sa.String(length=100), nullable=False),
        sa.Column('password_hash', sa.String(length=255), nullable=False),
        sa.Column('created_at', sa.DateTime(), nullable=True),
        sa.Column('updated_at', sa.DateTime(), nullable=True),
        sa.PrimaryKeyConstraint('id'),
        sa.UniqueConstraint('username'),
        sa.UniqueConstraint('email')
    )
    
    # 创建索引
    op.create_index(op.f('ix_users_username'), 'users', ['username'], unique=True)


def downgrade():
    # 删除索引
    op.drop_index(op.f('ix_users_username'), table_name='users')
    # 删除表
    op.drop_table('users')

2.6 手动迁移操作

# 添加列
def upgrade():
    op.add_column('users', sa.Column('phone', sa.String(20), nullable=True))

def downgrade():
    op.drop_column('users', 'phone')

# 删除列
def upgrade():
    op.drop_column('users', 'phone')

# 修改列
def upgrade():
    op.alter_column('users', 'username',
        existing_type=sa.String(50),
        type_=sa.String(100),
        existing_nullable=False
    )

# 添加外键
def upgrade():
    op.create_foreign_key(
        'fk_posts_user_id', 
        'posts', 'users', 
        ['user_id'], ['id']
    )

def downgrade():
    op.drop_constraint('fk_posts_user_id', 'posts', type_='foreignkey')

# 执行原生SQL
def upgrade():
    op.execute("UPDATE users SET status = 'active' WHERE status IS NULL")

# 批量操作（适合SQLite等不支持某些操作的数据库）
def upgrade():
    with op.batch_alter_table('users') as batch_op:
        batch_op.add_column(sa.Column('phone', sa.String(20)))
        batch_op.alter_column('username', type_=sa.String(100))

三、最佳实践

3.1 项目结构推荐

project/
├── app/
│   ├── __init__.py
│   ├── database.py      # 数据库连接和Session
│   ├── models/          # 模型定义
│   │   ├── __init__.py
│   │   ├── base.py      # Base定义
│   │   ├── user.py
│   │   └── post.py
│   └── schemas/         # Pydantic 模型
├── alembic/
│   ├── versions/
│   ├── env.py
│   └── ...
├── alembic.ini
└── main.py

3.2 异步支持

# database.py
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
from sqlalchemy.orm import declarative_base

DATABASE_URL = "mysql+aiomysql://user:password@localhost/dbname"

engine = create_async_engine(DATABASE_URL, echo=True)

AsyncSessionLocal = async_sessionmaker(
    engine, class_=AsyncSession, expire_on_commit=False
)

Base = declarative_base()

# 异步操作示例
async def get_users_async():
    async with AsyncSessionLocal() as session:
        result = await session.execute(select(User))
        return result.scalars().all()

3.3 迁移注意事项

生产环境谨慎使用 autogenerate
- 自动生成可能遗漏某些变更或产生意外的修改
- 建议人工审核每个迁移脚本
测试迁移的上下兼容性
- 确保 downgrade 能正确回滚
- 在测试环境先验证迁移
大数据表迁移策略
- 添加列时使用 server_default 避免锁表
- 考虑分批更新数据

# 安全添加非空列（大数据表）
def upgrade():
    op.add_column('users', sa.Column('status', sa.String(20), server_default='active'))
    # 后续再分批更新后移除默认值

四、常见问题

4.1 迁移版本冲突

当多人开发时可能出现版本冲突：

# 合并多个头版本
alembic merge -m "merge branches" head1 head2

4.2 模型导入问题

确保 env.py 中正确导入所有模型：

# 方式1：显式导入每个模型
from models import Base, User, Post

# 方式2：在 Base 导入后，导入所有模型模块
from models.base import Base
import models.user  # noqa
import models.post  # noqa

4.3 SQLite 外键约束

SQLite 默认不启用外键约束，需要在 env.py 中配置：

def run_migrations_online():
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix='sqlalchemy.',
        poolclass=pool.NullPool
    )

    with connectable.connect() as connection:
        # 启用外键约束（SQLite）
        connection.execute(sa.text('PRAGMA foreign_keys=ON'))
        
        context.configure(
            connection=connection,
            target_metadata=target_metadata
        )

        with context.begin_transaction():
            context.run_migrations()

五、参考资源

Read All

Docker Compose 安装 Apache Superset 记录

2026-01-13

docker

docker superset bi

安装docker-compose版本 apache-superset记录

bi看板, Superset 4.0.2版本

Read All

AI大模型学习指南 - 从入门到精通

2025-12-12

skill

AI LLM 机器学习深度学习

AI大模型学习指南

本指南提供了一个系统性的AI大模型学习路径，从基础概念到高级应用，帮助学习者循序渐进地掌握大语言模型相关技术。

学习路径概览

阶段划分

基础入门 (1-2个月) - 精力投入: ⭐⭐
核心理论 (2-3个月) - 精力投入: ⭐⭐⭐⭐
实践应用 (3-4个月) - 精力投入: ⭐⭐⭐⭐⭐
高级进阶 (持续学习) - 精力投入: ⭐⭐⭐⭐⭐

第一阶段：基础入门 (精力投入: ⭐⭐)

1.1 AI基础概念理解

学习目标: 建立对AI和机器学习的基本认知

学习内容:

人工智能发展历史和现状
机器学习 vs 深度学习 vs 大模型的区别
什么是大语言模型(LLM)
常见的大模型应用场景

推荐资源:

吴恩达机器学习课程 - Coursera
3Blue1Brown神经网络系列 - YouTube
《人工智能：一种现代方法》- Stuart Russell & Peter Norvig

时间安排: 2-3周难度: 初级

1.2 编程基础准备

学习目标: 掌握AI开发必需的编程技能

学习内容:

Python基础语法和数据结构
NumPy数组操作
Pandas数据处理
Matplotlib/Seaborn数据可视化
Jupyter Notebook使用

推荐资源:

时间安排: 3-4周难度: 初级

1.3 数学基础复习

学习目标: 巩固AI所需的数学基础

学习内容:

线性代数：矩阵运算、特征值、向量空间
微积分：导数、梯度、链式法则
概率统计：贝叶斯定理、概率分布
信息论基础：熵、互信息

推荐资源:

3Blue1Brown线性代数系列
Khan Academy统计学
《深度学习的数学》- 涌井良幸

时间安排: 2-3周难度: 中级

第二阶段：核心理论 (精力投入: ⭐⭐⭐⭐)

2.1 深度学习基础

学习目标: 理解神经网络和深度学习原理

学习内容:

感知机和多层感知机
反向传播算法
激活函数、损失函数、优化器
正则化技术(Dropout, Batch Normalization)
卷积神经网络(CNN)基础

推荐资源:

Deep Learning Specialization - Andrew Ng
《深度学习》- Ian Goodfellow, Yoshua Bengio, Aaron Courville
PyTorch官方教程

时间安排: 4-5周难度: 中高级

2.2 自然语言处理基础

学习目标: 掌握NLP核心概念和传统方法

学习内容:

文本预处理技术
词袋模型、TF-IDF
Word2Vec、GloVe词向量
循环神经网络(RNN, LSTM, GRU)
序列到序列模型(Seq2Seq)

推荐资源:

CS224N: Natural Language Processing - Stanford
《自然语言处理综论》- Daniel Jurafsky & James H. Martin
Hugging Face NLP Course

时间安排: 3-4周难度: 中高级

2.3 Transformer架构深入

学习目标: 深入理解Transformer模型架构

学习内容:

注意力机制(Attention Mechanism)
自注意力(Self-Attention)
多头注意力(Multi-Head Attention)
位置编码(Positional Encoding)
Transformer编码器和解码器
BERT、GPT架构对比

推荐资源:

Attention Is All You Need - 原始论文
The Illustrated Transformer - Jay Alammar
Transformer模型详解 - 知乎专栏

时间安排: 3-4周难度: 高级

第三阶段：实践应用 (精力投入: ⭐⭐⭐⭐⭐)

3.1 预训练模型使用

学习目标: 学会使用现有的预训练大模型

学习内容:

Hugging Face Transformers库使用
模型加载和推理
Tokenizer使用技巧
常见预训练模型对比(BERT, RoBERTa, GPT系列)
模型量化和优化

推荐资源:

实践项目:

文本分类任务
情感分析应用
问答系统构建

时间安排: 4-5周难度: 中高级

3.2 模型微调技术

学习目标: 掌握针对特定任务的模型微调方法

学习内容:

全参数微调(Full Fine-tuning)
参数高效微调(PEFT)
LoRA(Low-Rank Adaptation)
Adapter方法
Prompt Tuning技术
数据集构建和预处理

推荐资源:

实践项目:

领域特定文本生成
多语言翻译模型
代码生成助手

时间安排: 5-6周难度: 高级

3.3 大模型训练基础

学习目标: 了解大模型训练的基本流程和技术

学习内容:

分布式训练基础
数据并行 vs 模型并行
梯度累积和混合精度训练
学习率调度策略
训练监控和调试
模型评估指标

推荐资源:

实践项目:

小规模语言模型训练
多GPU训练实验

时间安排: 6-8周难度: 高级

第四阶段：高级进阶 (精力投入: ⭐⭐⭐⭐⭐)

4.1 大模型架构创新

学习目标: 深入研究最新的模型架构和优化技术

学习内容:

GPT系列演进(GPT-1到GPT-4)
Claude、LLaMA等模型架构分析
MoE(Mixture of Experts)架构
长序列处理技术
多模态大模型(Vision-Language Models)

推荐资源:

时间安排: 持续学习难度: 专家级

4.2 强化学习与人类反馈

学习目标: 掌握RLHF等高级训练技术

学习内容:

强化学习基础
PPO(Proximal Policy Optimization)
RLHF(Reinforcement Learning from Human Feedback)
Constitutional AI
安全性和对齐问题

推荐资源:

时间安排: 持续学习难度: 专家级

4.3 应用系统开发

学习目标: 构建完整的AI应用系统

学习内容:

RAG(Retrieval-Augmented Generation)系统
向量数据库使用
Agent框架开发
API服务部署
性能优化和扩展

推荐资源:

实践项目:

智能客服系统
知识问答助手
代码审查工具

时间安排: 持续学习难度: 专家级

精力投入对比分析

各阶段精力分配建议

学习阶段	精力投入	时间分配	主要挑战	学习重点
基础入门	⭐⭐	1-2个月	概念理解	建立基础认知
核心理论	⭐⭐⭐⭐	2-3个月	数学原理	深入理解机制
实践应用	⭐⭐⭐⭐⭐	3-4个月	工程实现	动手能力培养
高级进阶	⭐⭐⭐⭐⭐	持续学习	前沿跟踪	创新和优化

关键投入点分析

高投入收益点 (⭐⭐⭐⭐⭐):

Transformer架构理解
实际项目开发经验
模型微调技术
系统工程能力

中等投入点 (⭐⭐⭐):

数学基础巩固
编程技能提升
理论知识学习

基础投入点 (⭐⭐):

概念性知识
工具使用熟悉
环境搭建

学习建议和注意事项

学习策略

循序渐进: 不要跳跃式学习，每个阶段都要扎实掌握
理论结合实践: 学习理论的同时要动手实践
持续跟进: AI领域发展迅速，要保持学习的连续性
社区参与: 加入相关技术社区，与同行交流

常见误区

过分追求最新技术而忽视基础
只看不练，缺乏实际动手经验
学习过于分散，没有系统性规划
忽视数学基础的重要性

职业发展路径

研究方向: 算法研究员、AI科学家
工程方向: AI工程师、MLOps工程师
应用方向: AI产品经理、解决方案架构师
创业方向: AI创业者、技术顾问

参考资源汇总

在线课程平台

Coursera - 高质量学术课程
edX - 名校公开课
Udacity - 实践导向课程
Fast.ai - 实用深度学习

技术社区

Hugging Face - 模型和数据集社区
Papers with Code - 论文和代码
GitHub - 开源项目
Reddit r/MachineLearning - 技术讨论

学术资源

arXiv - 最新论文预印本
Google Scholar - 学术搜索
Semantic Scholar - AI驱动的学术搜索

最后更新: 2025年12月12日

本学习指南会根据AI技术发展持续更新，建议定期查看最新版本。

Read All

Ollama 学习笔记（由易到难）

2025-12-01

skill

ollama ai llm

认识 Ollama

Ollama 是本地运行大语言模型的工具，支持 Windows、macOS、Linux。
通过一条命令即可拉取和运行模型，提供 HTTP API，易于集成到应用。
适合开发者在本地做原型、私有数据推理、离线研发。
官方文档：https://ollama.com/docs

安装与启动（入门）

下载地址：https://ollama.com/download
安装后默认运行本地服务，API 端口为 11434。
基本检查：

ollama --version
ollama list

首次运行示例：

ollama run llama3 "你好，介绍下你自己"

更多：安装与使用概览 https://ollama.com/docs/usage

模型管理（入门）

拉取模型：

ollama pull llama3
ollama pull qwen2
ollama pull mistral

列出/删除模型：

ollama list
ollama rm llama3

模型目录与体积说明（参考）：https://ollama.com/docs/models

基本对话与参数（基础）

直接对话：

ollama run qwen2

一次性提示：

ollama run mistral -p "请用要点解释 Transformer 的注意力机制"

常用参数（更多见 https://ollama.com/docs/parameters）：
-p 传入 prompt；-m 指定模型；-t 模板相关（在 Modelfile 中更常见）。
推理控制：temperature、top_p、top_k、num_predict、repeat_penalty、mirostat。
上下文长度：num_ctx（影响长文能力与内存占用）。

本地 API 调用（基础）

API 概览：https://ollama.com/docs/api
生成文本（流式/非流式）：POST /api/generate
多轮对话：POST /api/chat
curl 示例：

curl -X POST http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "prompt": "用三句话解释RAG",
    "stream": false
  }'

Python 示例：

import requests

url = "http://localhost:11434/api/chat"
payload = {
    "model": "llama3",
    "messages": [
        {"role": "user", "content": "给我一个Python生成示例"}
    ],
    "stream": False
}
resp = requests.post(url, json=payload, timeout=60)
print(resp.json())

Node.js 示例：

const fetch = require('node-fetch');

(async () => {
  const res = await fetch('http://localhost:11434/api/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ model: 'qwen2', prompt: '列出三条LLM提示工程建议', stream: false })
  });
  const data = await res.json();
  console.log(data);
})();

Embeddings（进阶）

生成向量：POST /api/embeddings
文档：https://ollama.com/docs/embeddings

curl -X POST http://localhost:11434/api/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "prompt": "大语言模型是什么"
  }'

用途：为 RAG、语义搜索、相似度检索提供向量表示；可配合 faiss、pgvector、milvus 等库。

Modelfile 与自定义模型（进阶）

文档：https://docs.ollama.com/modelfile
通过 Modelfile 在基础模型上添加系统提示、模板、参数等，生成自己的可复用模型。

# 文件名: Modelfile
FROM llama3
PARAMETER temperature 0.7
PARAMETER num_ctx 4096
SYSTEM "你是一名资深中文助理，回答要简洁、有条理。"
TEMPLATE "用户：\n助理："

ollama create my-llama -f Modelfile
ollama run my-llama -p "请用要点解释Attention"

常见参数与说明：https://ollama.com/docs/parameters
将 keep_alive 设置为如 5m 可提高多次调用的响应速度（模型常驻内存）。

个人模型制作与推送（进阶）

模型制作概述

制作思路：基于基础模型，通过 Modelfile 配置系统提示、模板、参数，必要时引入 LoRA 适配器，创建个人化模型。
适用场景：定制化助手、特定领域知识库、风格化对话、企业私有模型等。
参考文档：https://docs.ollama.com/modelfile、https://docs.ollama.com/import

Modelfile 详解

Modelfile 是定义自定义模型的核心配置文件，支持以下指令：

基础指令说明

FROM <模型名>：指定基础模型（必需）
SYSTEM <提示词>：设置系统提示，定义模型角色和行为
TEMPLATE <模板字符串>：定义对话模板格式
PARAMETER <参数名> <值>：设置模型推理参数
ADAPTER <路径>：引入 LoRA 适配器（可选）
LICENSE <许可证>：声明模型许可证
MESSAGE <角色> <内容>：添加示例对话消息

Modelfile 语法格式详解

1. FROM 指令

语法：

FROM <模型名>[:<标签>]

说明：

必需指令，必须放在文件开头
指定基础模型，可以是官方模型或已存在的自定义模型
支持标签指定版本（如 llama3:8b）

示例：

FROM llama3              # 使用默认版本
FROM llama3:8b           # 使用 8b 版本
FROM qwen2:7b            # 使用 qwen2 的 7b 版本
FROM myuser/mymodel      # 使用自定义模型
FROM myuser/mymodel:1.0  # 使用自定义模型的特定版本

2. SYSTEM 指令

语法：

SYSTEM "<单行提示词>"
# 或
SYSTEM """多行提示词
可以包含换行
支持多行内容"""

说明：

定义模型的系统提示词，描述模型角色、行为规范
可以使用单引号 " 或三引号 """ 包裹
三引号支持多行内容，保留换行格式
可以多次使用，后面的会覆盖前面的

示例：

# 单行
SYSTEM "你是一名专业的AI助手。"

# 多行
SYSTEM """你是一名资深软件工程师。
你的职责包括：
1. 编写高质量代码
2. 进行代码审查
3. 提供技术建议"""

# 使用变量（在模板中）
SYSTEM "你是一个编程专家。"

3. TEMPLATE 指令

语法：

TEMPLATE "<模板字符串>"
# 或
TEMPLATE """多行模板
支持换行"""

说明：

定义对话模板，控制用户输入和模型输出的格式
使用 Go 模板语法（``）
可用变量：
- ``：用户输入
- ``：系统提示词
- ``：模型响应（在生成时可用）

模板语法：

``：输出变量值
...：条件判断
......：条件判断（带 else）
\n：换行符
\t：制表符

示例：

# 简单模板
TEMPLATE "用户：\n助手："

# 条件模板
TEMPLATE """系统：

用户：

助手："""

# 复杂模板（多轮对话格式）
TEMPLATE """<|system|>
<|end|>
<|user|>
<|end|>
<|assistant|>
"""

常见模型模板格式：

# ChatML 格式（OpenAI 风格）
TEMPLATE """<|im_start|>system
<|im_end|>
<|im_start|>user
<|im_end|>
<|im_start|>assistant
"""

# Alpaca 格式
TEMPLATE """Below is an instruction that describes a task. Write a response that appropriately completes the request.

### Instruction:


### Response:
"""

# Vicuna 格式
TEMPLATE """USER: 
ASSISTANT: """

4. PARAMETER 指令

语法：

PARAMETER <参数名> <值>

说明：

设置模型推理参数
参数名不区分大小写
可以多次使用设置不同参数
数值参数可以是整数或浮点数

常用参数列表：

参数名	类型	默认值	说明	取值范围
`temperature`	float	0.8	采样温度，控制随机性	0.0-2.0
`top_p`	float	0.9	核采样参数	0.0-1.0
`top_k`	int	40	Top-K 采样，限制候选词数	1-100
`num_ctx`	int	2048	上下文窗口大小（token数）	512-32768
`num_predict`	int	-1	最大生成 token 数（-1 表示无限制）	-1 或正整数
`repeat_penalty`	float	1.1	重复惩罚系数	0.0-2.0
`repeat_last_n`	int	64	考虑重复惩罚的最近 token 数	0-2048
`seed`	int	-1	随机种子（-1 表示随机）	-1 或非负整数
`numa`	bool	false	是否使用 NUMA	true/false
`num_thread`	int	自动	CPU 线程数	正整数
`num_gpu`	int	自动	GPU 层数	非负整数
`main_gpu`	int	0	主 GPU 索引	非负整数
`low_vram`	bool	false	低显存模式	true/false
`f16_kv`	bool	true	使用 FP16 存储 KV 缓存	true/false
`logits_all`	bool	false	返回所有 token 的 logits	true/false
`vocab_only`	bool	false	仅加载词汇表	true/false
`use_mmap`	bool	true	使用内存映射	true/false
`use_mlock`	bool	false	锁定内存	true/false
`embedding_only`	bool	false	仅用于 embeddings	true/false
`mirostat`	int	0	Mirostat 采样算法（0=禁用，1=Mirostat，2=Mirostat 2.0）	0/1/2
`mirostat_lr`	float	0.1	Mirostat 学习率	0.0-1.0
`mirostat_eta`	float	0.1	Mirostat eta 参数	0.0-1.0
`penalize_newline`	bool	true	惩罚换行符	true/false
`stop`	string	-	停止序列（可多次使用）	字符串

示例：

# 基础参数
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER top_k 40

# 上下文和生成长度
PARAMETER num_ctx 4096
PARAMETER num_predict 2048

# 重复控制
PARAMETER repeat_penalty 1.1
PARAMETER repeat_last_n 64

# 随机种子（用于可复现性）
PARAMETER seed 42

# 停止序列（可多次使用）
PARAMETER stop "用户："
PARAMETER stop "Human:"
PARAMETER stop "\n\n\n"

# GPU 配置
PARAMETER num_gpu 2
PARAMETER main_gpu 0
PARAMETER low_vram true

# 采样算法
PARAMETER mirostat 2
PARAMETER mirostat_lr 0.1
PARAMETER mirostat_eta 0.1

5. MESSAGE 指令

语法：

MESSAGE <角色> "<内容>"
# 或
MESSAGE <角色> """多行内容
支持换行"""

说明：

添加示例对话消息（few-shot learning）
用于训练模型理解特定对话格式或提供示例
角色通常是 user 或 assistant
可以多次使用，按顺序组成对话历史

示例：

# 单轮对话示例
MESSAGE user "什么是 Python？"
MESSAGE assistant "Python 是一种高级编程语言，以简洁和可读性著称。"

# 多轮对话示例
MESSAGE user "如何学习编程？"
MESSAGE assistant "学习编程可以从以下几个方面入手：\n1. 选择一门语言\n2. 练习基础语法\n3. 做项目实践"

MESSAGE user "推荐一些学习资源"
MESSAGE assistant "推荐资源：\n- 官方文档\n- 在线教程\n- 编程练习平台"

# 复杂格式示例
MESSAGE user """请帮我写一个 Python 函数，计算斐波那契数列的第 n 项。"""
MESSAGE assistant """```python
def fibonacci(n):
    if n <= 1:
        return n
    a, b = 0, 1
    for _ in range(2, n + 1):
        a, b = b, a + b
    return b
```"""

6. ADAPTER 指令

语法：

ADAPTER <路径>

说明：

引入 LoRA 适配器
路径可以是相对路径或绝对路径
适配器目录应包含适配器权重文件

示例：

# 相对路径
ADAPTER ./lora_adapter
ADAPTER ./adapters/code_assistant

# 绝对路径
ADAPTER /home/user/adapters/my_adapter
ADAPTER C:\Users\user\adapters\my_adapter

7. LICENSE 指令

语法：

LICENSE "<许可证名称>"
# 或
LICENSE """多行许可证文本
可以包含完整的许可证内容"""

说明：

声明模型许可证
可以是许可证名称或完整许可证文本

示例：

# 许可证名称
LICENSE "MIT"
LICENSE "Apache-2.0"
LICENSE "CC-BY-4.0"

# 完整许可证文本
LICENSE """MIT License

Copyright (c) 2024

Permission is hereby granted...
"""

8. 注释语法

语法：

# 单行注释
# 这是注释内容

说明：

使用 # 开头表示注释
注释会被忽略，不影响模型配置
可用于说明配置意图

示例：

# 这是一个代码助手模型
FROM llama3:8b

# 系统提示：定义模型角色
SYSTEM "你是一名专业的代码助手。"

# 推理参数：平衡创造性和准确性
PARAMETER temperature 0.7  # 适中的随机性
PARAMETER top_p 0.9        # 核采样

9. 多行字符串语法

语法：

# 使用三引号
"""多行内容
可以包含换行
保留格式"""

说明：

使用三个双引号 """ 包裹多行内容
保留换行和空格格式
适用于 SYSTEM、TEMPLATE、MESSAGE、LICENSE 等指令

示例：

SYSTEM """你是一名专业助手。
你的回答需要：
1. 准确
2. 详细
3. 有条理"""

TEMPLATE """系统：

用户：

助手："""

10. 指令顺序与优先级

推荐顺序：

FROM（必需，放在最前）
ADAPTER（如果有）
SYSTEM
TEMPLATE
PARAMETER（可以多个）
MESSAGE（可以多个）
LICENSE

优先级规则：

相同指令多次使用时，后面的会覆盖前面的
PARAMETER 可以多次使用设置不同参数
MESSAGE 按顺序累积，形成对话历史

示例：

# 正确的顺序示例
FROM llama3:8b
ADAPTER ./my_adapter
SYSTEM "你是一名助手。"
TEMPLATE "用户：\n助手："
PARAMETER temperature 0.7
PARAMETER num_ctx 4096
MESSAGE user "示例1"
MESSAGE assistant "回复1"
MESSAGE user "示例2"
MESSAGE assistant "回复2"
LICENSE "MIT"

11. 转义字符

常用转义字符：

\n：换行符
\t：制表符
\"：双引号
\\：反斜杠
\r：回车符

示例：

# 在单引号字符串中使用转义
TEMPLATE "用户：\n助手："

# 在多行字符串中也可以使用
SYSTEM "第一行\n第二行\n第三行"

完整 Modelfile 示例

# 文件名: Modelfile
# 基于 llama3 创建专业代码助手

FROM llama3:8b

# 系统提示：定义模型角色
SYSTEM """你是一名资深的软件工程师和代码审查专家。
你的回答需要：
1. 代码示例清晰、可运行
2. 解释简洁、有条理
3. 提供最佳实践建议
4. 指出潜在问题和改进方向"""

# 对话模板：定义用户和助手的交互格式
TEMPLATE """系统：

用户：

助手："""

# 推理参数配置
PARAMETER temperature 0.7        # 创造性（0-1，越高越随机）
PARAMETER top_p 0.9              # 核采样参数
PARAMETER top_k 40               # Top-K 采样
PARAMETER num_ctx 4096           # 上下文窗口大小
PARAMETER num_predict 2048       # 最大生成 token 数
PARAMETER repeat_penalty 1.1     # 重复惩罚（>1 减少重复）
PARAMETER seed 42                # 随机种子（固定可复现）

# 示例对话（few-shot learning）
MESSAGE user "如何优化 Python 列表查找性能？"
MESSAGE assistant """对于频繁查找，可以使用集合（set）替代列表：

```python
# 慢：O(n)
if item in my_list:
    pass

# 快：O(1)
if item in my_set:
    pass

对于有序数据，使用二分查找（bisect 模块）。”””

许可证声明

LICENSE “MIT”

#### 不同场景的 Modelfile 示例

**示例 1：中文对话助手**

```dockerfile
FROM qwen2:7b
SYSTEM "你是一个友好、专业的中文AI助手。回答要自然、易懂，适当使用表情符号。"
TEMPLATE "用户：\n\n助手："
PARAMETER temperature 0.8
PARAMETER num_ctx 8192

示例 2：技术文档生成器

FROM mistral:7b
SYSTEM """你是一个技术文档编写专家。
输出格式要求：
- 使用 Markdown 格式
- 代码块包含语言标识
- 提供清晰的步骤说明
- 包含注意事项和最佳实践"""
TEMPLATE "\n\n请按照上述要求生成文档：\n\n"
PARAMETER temperature 0.3
PARAMETER num_predict 4096

示例 3：数据分析助手

FROM llama3:8b
SYSTEM "你擅长数据分析和统计。回答时提供具体的数据处理步骤、代码示例和可视化建议。"
PARAMETER temperature 0.5
PARAMETER num_ctx 16384

创建自定义模型

基本创建流程

# 1. 准备 Modelfile（在当前目录创建 Modelfile 文件）
cat > Modelfile << 'EOF'
FROM llama3
SYSTEM "你是一名专业助理。"
PARAMETER temperature 0.7
EOF

# 2. 创建模型
ollama create mymodel -f Modelfile

# 3. 测试模型
ollama run mymodel -p "介绍一下你自己"

量化选项（降低资源占用）

# 不同量化等级（从高到低质量，从大到小体积）
ollama create mymodel -f Modelfile --quantize q8_0    # 8位量化，质量最高
ollama create mymodel -f Modelfile --quantize q6_K     # 6位量化，平衡选择
ollama create mymodel -f Modelfile --quantize q4_K_M   # 4位量化，推荐
ollama create mymodel -f Modelfile --quantize q4_0     # 4位量化，最小体积

量化等级说明：

q8_0：8位量化，接近原始质量，体积较大
q6_K：6位量化，质量与体积的平衡点
q4_K_M：4位量化（中等），推荐用于大多数场景
q4_0：4位量化（基础），体积最小但质量略低

查看和管理模型

# 查看模型详细信息
ollama show mymodel

# 查看模型的 Modelfile 配置
ollama show mymodel --modelfile

# 列出所有模型
ollama list

# 复制模型（用于创建变体）
ollama cp mymodel mymodel-v2

# 删除模型
ollama rm mymodel

LoRA 适配器集成

LoRA（Low-Rank Adaptation）是一种参数高效的微调方法，可以在不修改基础模型的情况下添加特定能力。

准备 LoRA 适配器

# LoRA 适配器通常是一个目录，包含适配器权重文件
# 目录结构示例：
# adapter_dir/
#   ├── adapter_config.json
#   └── adapter_model.bin

在 Modelfile 中使用 LoRA

FROM llama3:8b
ADAPTER ./adapter_dir
SYSTEM "你是一名经过专业领域训练的AI助手。"
PARAMETER temperature 0.7

创建带 LoRA 的模型

# 确保 adapter_dir 目录存在且包含适配器文件
ollama create mymodel-lora -f Modelfile

注意事项：

LoRA 适配器需要与基础模型兼容
适配器文件通常由训练框架（如 PEFT、LoRA）生成
适配器可以叠加使用，但需要确保兼容性

模型推送详细流程

前置准备

注册 Ollama 账号
- 访问 https://ollama.com/
- 注册并登录账号

获取 Ollama Public Key

# 查看本机的公钥
ollama key
# 或查看公钥文件位置（通常在 ~/.ollama/id_ed25519.pub）

添加公钥到账号
- 登录 https://ollama.com/
- 进入 Settings → Ollama Keys
- 点击 “Add Key”，粘贴公钥内容
- 保存设置

推送步骤详解

步骤 1：命名模型（使用命名空间）

模型名称必须遵循 <用户名>/<模型名> 的格式：

# 如果模型已存在，需要复制并重命名
ollama cp mymodel <你的用户名>/mymodel

# 或者创建时直接使用命名空间
ollama create <你的用户名>/mymodel -f Modelfile

示例（假设用户名为 john）：

ollama cp mymodel john/code-assistant

步骤 2：验证模型

推送前建议先本地测试：

# 测试模型功能
ollama run <你的用户名>/mymodel -p "测试提示"

# 查看模型信息
ollama show <你的用户名>/mymodel

步骤 3：推送模型

# 推送模型到 Ollama 模型库
ollama push <你的用户名>/mymodel

推送过程会显示进度：

pushing manifest
pushing 2/2 layers (100%)
pushed successfully

步骤 4：验证推送结果

访问 https://ollama.com/library 查看你的模型

或使用 API 检查：

curl https://ollama.com/api/tags | grep "<你的用户名>/mymodel"

版本管理与标签

使用标签管理模型版本，便于迭代和回滚：

# 创建带版本标签的模型
ollama cp <你的用户名>/mymodel <你的用户名>/mymodel:1.0
ollama cp <你的用户名>/mymodel <你的用户名>/mymodel:latest

# 推送特定版本
ollama push <你的用户名>/mymodel:1.0
ollama push <你的用户名>/mymodel:latest

# 更新模型后创建新版本
ollama cp <你的用户名>/mymodel <你的用户名>/mymodel:2.0
ollama push <你的用户名>/mymodel:2.0

版本命名建议：

latest：最新稳定版
1.0、1.1、2.0：语义化版本号
dev、beta：开发/测试版本
2024-12-01：日期版本

他人使用你的模型

推送成功后，其他人可以通过以下方式使用：

# 拉取模型
ollama pull <你的用户名>/mymodel

# 或拉取特定版本
ollama pull <你的用户名>/mymodel:1.0

# 运行模型
ollama run <你的用户名>/mymodel -p "你好"

推送常见问题与解决方案

问题 1：推送失败 - 认证错误

症状：

Error: unauthorized

解决方案：

确认已登录 https://ollama.com/
检查公钥是否正确添加到账号

重新生成密钥对（如需要）：

# 删除旧密钥（谨慎操作）
rm ~/.ollama/id_ed25519*
# Ollama 会在下次操作时自动生成新密钥
ollama key  # 查看新公钥

问题 2：推送失败 - 网络超时

症状：

Error: timeout

解决方案：

检查网络连接

使用代理（如需要）：

export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port
ollama push <你的用户名>/mymodel

分块推送大模型（Ollama 自动处理）

问题 3：模型名称格式错误

症状：

Error: invalid model name

解决方案：

确保模型名称格式为 <用户名>/<模型名>
用户名必须与 Ollama 账号一致
模型名不能包含特殊字符（建议使用字母、数字、连字符）

问题 4：推送进度缓慢

原因与优化：

模型体积大：考虑使用量化版本
网络带宽限制：使用稳定网络环境
首次推送较慢：后续更新只推送变更部分

模型更新与维护

更新已推送的模型

# 1. 修改 Modelfile
vim Modelfile

# 2. 重新创建模型（使用相同名称）
ollama create <你的用户名>/mymodel -f Modelfile

# 3. 推送更新
ollama push <你的用户名>/mymodel

删除已推送的模型

# 注意：删除操作需要谨慎，可能影响其他用户
# 在 Ollama 网站上进行删除操作更安全

模型描述与文档

在推送模型时，建议：

在 Modelfile 中添加注释说明模型用途
在 Ollama 网站为模型添加描述
提供使用示例和参数说明

高级技巧

1. 模型组合与继承

# 基于已有自定义模型创建新模型
FROM <你的用户名>/mymodel
SYSTEM "在原有基础上，你还需要擅长数据分析。"
PARAMETER temperature 0.6

2. 条件模板

TEMPLATE """系统指令：

用户：

助手："""

3. 多轮对话示例

MESSAGE user "什么是 RAG？"
MESSAGE assistant "RAG（Retrieval-Augmented Generation）是一种结合检索和生成的技术..."

MESSAGE user "它有什么优势？"
MESSAGE assistant "RAG 的主要优势包括：1. 可以访问最新信息 2. 减少幻觉..."

API 参考

推送接口：https://docs.ollama.com/api/push
模型管理：https://docs.ollama.com/api/tag
Modelfile 完整文档：https://docs.ollama.com/modelfile

性能与上下文（进阶）

上下文长度 num_ctx：增大可处理更长文本，但显著提升内存与算力需求。
生成长度 num_predict：限制最大输出 token 数，避免响应过长。
流式输出：API 中 stream: true 可边生成边传输，提升交互体验。
并发建议：控制并发到机器可承受范围；复用常驻模型以减少冷启动。

RAG 快速示例（进阶）

指南与案例：https://ollama.com/docs/examples
思路：
1）将本地文档分块并生成 embeddings（用 Ollama 的 /api/embeddings）。
2）存入向量库（FAISS/pgvector），检索相似片段。
3）将检索到的内容拼接为上下文，走 /api/chat 作为系统/用户提示。

多模型与多模态（进阶）

可同时安装多种模型：llama3、qwen2、mistral、phi3 等。
多模态（图像理解）模型如 llava 需要额外输入；参考：https://ollama.com/docs/models

Windows 常见问题（进阶）

端口占用：确保 11434 未被占用；或通过环境变量更改端口。
显存/内存不足：选择更小的量化模型（如 q4）；降低 num_ctx。
启动失败排查：查看日志与服务状态；参考：https://ollama.com/docs/usage

实用命令速查（综合）

# 拉取/运行
ollama pull llama3
ollama run llama3 -p "用5点说明提示工程"

# 查看模型
ollama list

# 删除模型
ollama rm llama3

# 创建自定义模型
ollama create my-llama -f Modelfile
ollama run my-llama -p "测试"

# 生成向量
curl -s http://localhost:11434/api/embeddings -d '{"model":"llama3","prompt":"示例"}'

参考资料

官方文档主页：https://ollama.com/docs
下载页：https://ollama.com/download
使用指南：https://ollama.com/docs/usage
API：https://ollama.com/docs/api
Embeddings：https://ollama.com/docs/embeddings
Modelfile：https://ollama.com/docs/modelfile
参数：https://ollama.com/docs/parameters
模型目录：https://ollama.com/docs/models

Read All

Python Libs Install

2025-10-23

记录一下python下面各种依赖同步方式与虚拟环境维护方式

Read All
封装Java Jar包工具-制作子证书与签名APK功能

2025-08-20

java

java maven 证书签名

封装java jar包工具制作子证书与签名apk功能

业务需要,封装java

Read All

1/20

Welcome to Barry's Blog!

Python SQLAlchemy与Alembic数据库迁移笔记

Python SQLAlchemy与Alembic数据库迁移

前言

一、SQLAlchemy 基础

1.1 安装

1.2 连接数据库

1.3 定义模型

1.4 Session 操作

1.5 查询进阶

二、Alembic 数据库迁移

2.1 安装与初始化

2.2 配置 alembic.ini

2.3 配置 env.py

2.4 常用迁移命令

2.5 迁移脚本示例

2.6 手动迁移操作

三、最佳实践

3.1 项目结构推荐

3.2 异步支持

3.3 迁移注意事项

四、常见问题

4.1 迁移版本冲突

4.2 模型导入问题

4.3 SQLite 外键约束

五、参考资源

Docker Compose 安装 Apache Superset 记录

安装docker-compose版本 apache-superset记录

AI大模型学习指南 - 从入门到精通

AI大模型学习指南

学习路径概览

阶段划分

第一阶段：基础入门 (精力投入: ⭐⭐)

1.1 AI基础概念理解

1.2 编程基础准备

1.3 数学基础复习

第二阶段：核心理论 (精力投入: ⭐⭐⭐⭐)

2.1 深度学习基础

2.2 自然语言处理基础

2.3 Transformer架构深入

第三阶段：实践应用 (精力投入: ⭐⭐⭐⭐⭐)

3.1 预训练模型使用

3.2 模型微调技术

3.3 大模型训练基础

第四阶段：高级进阶 (精力投入: ⭐⭐⭐⭐⭐)

4.1 大模型架构创新

4.2 强化学习与人类反馈

4.3 应用系统开发

精力投入对比分析

各阶段精力分配建议

关键投入点分析

学习建议和注意事项

学习策略

常见误区

职业发展路径

参考资源汇总

在线课程平台

技术社区

学术资源

Ollama 学习笔记（由易到难）

认识 Ollama

安装与启动（入门）

模型管理（入门）

基本对话与参数（基础）

本地 API 调用（基础）

Embeddings（进阶）

Modelfile 与自定义模型（进阶）

个人模型制作与推送（进阶）

模型制作概述

Modelfile 详解

基础指令说明

Modelfile 语法格式详解

1. FROM 指令

2. SYSTEM 指令

3. TEMPLATE 指令

4. PARAMETER 指令

5. MESSAGE 指令

6. ADAPTER 指令

7. LICENSE 指令

8. 注释语法

封装java jar包工具制作子证书与签名apk功能